Medipim BE - API V4

Developer documentation

POST /v4/products/query

(Last updated: 27/05/2025)

Request

Method

POST

URL

https://api.medipim.be/v4/products/query

Headers

Body

  • filter: one of the filters below; filters can be combined using and, or & not. (required)
  • sorting: one of the sortings below. (required)
  • page (required)
    • no: page number (zero-based)
    • size: one of 10, 50, 100 or 250 (defaults to 100)
Filter Description Parameters Examples
{"id": ...} Matches by product ID. One or more Medipim product IDs {"id": 1} or {"id": [1, 2]}
{"status": ...} Matches products by status. One or more product statuses.
Possible values: "active", "replaced" or "inactive". 		{"status": "active"} or {"status": ["replaced", "inactive"]}
{"ecommerce": ...}(⚠️ deprecated) Matches products by ecommerce status. One or more ecommerce statuses.
Possible values: `"yes"`, `"no"` or `"unknown"`. 		{"ecommerce": "yes"} or {"ecommerce": ["yes", "unknown"]}
{"organization": ...} Matches products by organization. One or more organization IDs. {"organization": 2} or {"organization": [2, 15]}
{"publicCategory": ...} Matches products by public category. One or more public category IDs. {"publicCategory": 12} or {"publicCategory": [3, 6]}
{"brand": ...} Matches products by brand. One or more brand IDs. {"brand": 4} or {"brand": [14, 3]}
{"productFamily": ...} Matches products by product family. One or more product family IDs. {"productFamily": 4} or {"productFamily": [14, 3]}
{"search": ...} Matches products by a specific search query. Array with 'query', 'locale' and (optional) 'type' key. {"search": {"query": "my query", "locale": "en", "type": "contains"}}
{"minimumContent": ...} Matches products with an image AND a description AND a public category. true or false. {"minimumContent": true} or {"minimumContent": false}
{"hasContent": ...} Matches products that have specific content.
Check field glossary for more info. 		Array with 'flag' and 'locale' key. {"hasContent": {"flag": "name", "locale": "en"}}
{"ean": ...} Matches products with specified EAN number.
 One or more EAN codes {"ean": "3574660696318"} or {"ean": ["01234567", "123456789012", "3401526293056", ...]}
{"gtin": ...} Matches products with specified GTIN number.
(⚠️ deprecated use ean14 filter instead) 		One or more GTIN codes {"gtin": "03664798014846"} or {"gtin": ["03664798014846", "07613326014816", ...]}
{"eanGtin8": ...} Matches products with specified EAN8 number. One or more EAN/GTIN codes {"eanGtin8": "01234567"} or {"eanGtin8": ["01234567", "87654321", ...]}
{"eanGtin12": ...} Matches products with specified EAN12 number. One or more EAN/GTIN codes {"eanGtin12": "123456789012"} or {"eanGtin12": ["123456789012", "210987654321", ...]}
{"eanGtin13": ...} Matches products with specified EAN13 number. One or more EAN/GTIN codes {"eanGtin13": "0012345678901"} or {"eanGtin13": ["0012345678901", "3210987654321", ...]}
{"eanGtin14": ...} Matches products with specified EAN14 / GTIN number. One or more EAN/GTIN codes {"eanGtin14": "01234567890123"} or {"eanGtin14": ["01234567890123", "43210987654321", ...]}
{"hsCode": ...} Matches products with specified HS code. String or integer {"hsCode": "010203"} or {"hsCode": ["010203", "010204", ...]}
{"cnk": ...} Matches products by CNK code. One or more CNKs {"cnk": "4444444"} or {"cnk": ["1234567", "4444444"]}
{"cti": ...} Matches products with specified CTI number. String. {"cti": "240904"}
{"nameCti": ...} Matches products with specified nameCti or grouping by name number. String. For more information {"nameCti": "603722"}
{"activeIngredient": ...} Matches products by active ingredients. One or more activeIngredient IDs. {"activeIngredient": [1, 2]}
{"conservation": ...} Matches products by conservation. One or more conservation types.
Possible values: room, refrigerator, fresh, frozen (string) 		{"conservation":"room"} or {"conservation": ["room", "frozen", ...]}
{"prescription": ...} Matches products with or without prescription. true or false. {"prescription": true} or {"prescription": false}
{"writtenRequestByPatient": ...} Matches products with or without request written by patient. true or false. {"writtenRequestByPatient": true} or {"writtenRequestByPatient": false}
{"supplyProblemDuration": ...} Matches products with one or more supply problems in a specific date rage. From and/or until date as unix timestamp(s) {"supplyProblemDuration": 1704063600} or {"supplyProblemDuration": {"from": 1704063600, "until": 1705705200}}
{"prescription": ...} Matches products with or without prescription. true or false. {"prescription": true} or {"prescription": false}
{"popularity": ...} Matches products by popularity. Array with 'value' and (optional) numerical 'operator' key.
If no operator is provided "eq" is used. 		{"popularity": {"value": 4}} or {"popularity": {"value": 4, "operator": "lte"}}
{"allowedSpecies": ...} Matches products by allowed species. One or more species
Possible values: `"human"`, `"veterinary"`, `"surface_maintenance"` or `"phytopharmacy"`. 		{"allowedSpecies":"human"} or {"allowedSpecies": ["human", "veterinary", ...]}
{"atcCategory": ...} Matches products with specified ATC category code. One or more ATC category IDs. {"atcCategory": "BC01D"} or {"atcCategory": ["BC01D", "A1", ...]}
{"apbCategory": ...} Matches products by APB category. One or more APB categories
Possible values: `"specialty`", `"homeopathy`", `"ostomy_incontinence`", `"bandages_related`", `"reactive`", `"hygiene`", `"cosmetics`", `"diet_nutrition`", `"other`", `"biocide`", `"medical_device`", `"accessory`", `"pesticides_agricultural`", `"diagnostic_tool`", `"unknown`" or `"material`" 		{"apbCategory":"homeopathy"} or {"apbCategory": ["material", "reactive"]}
{"bcfiCategory": ...} Matches products by BCFI category. One or BCFI category IDs. {"bcfiCategory": "0017566"} or {"bcfiCategory": ["0017566", "0000976"]}
{"narcotic": ...} Matches products that are either marked as narcotics or not. true or false. {"narcotic": true} or {"narcotic": false}
{"biocide": ...} Matches products that are either marked as biocides or not. true or false. {"biocide": true} or {"biocide": false}
{"attributes": ...} Matches products by attribute options. One or more attribute option IDs. {"attributes": 1} or {"attributes": [1,2]}
{"notApplicableField": ...} Matches products by not applicable fields. One or more fields {"notApplicableField": "productFamily"} or {"notApplicableField": ["productFamily", "brand"]}
{"officialDeletionAt": ...} Matches products with a specific commercial end date. Unix timestamp. {"officialDeletionAt": 1471525605} or {"officialDeletionAt": {"from": 1471525605, "until": 1571525605}}
{"createdAt": ...} Matches products created since the given time. Unix timestamp. {"createdAt": 1471525605} or {"createdAt": {"from": 1471525605, "until": 1571525605}}
{"updatedSince": ...} Matches products updated since the given time. Unix timestamp. {"updatedSince": 1471525605} or {"updatedSince": {"from": 1471525605, "until": 1571525605}}
{"and": [...]} Matches products that match all the given filters. A list of filters. {"and": [{"brand": [24, 65, ...]}, {"status": "active"}]}
{"or": [...]} Matches products that match any of the given filters. A list of filters. {"or": [{"publicCategory": [2, 16, ...]}, {"status": "active"}]}
{"not": ...} Matches products that do not match the given filter. A filter. {"not": {"publicCategory": 81}}
Sorting Description Parameters Examples
{"id": ...} Sort by Medipim ID "ASC" or "DESC" {"id": "ASC"} or {"id": "DESC"}
{"name": ...} Sort by Name Array containing "direction" and "locale" {"name": {"direction": "ASC", "locale": "en"}} or ...
{"cnk": ...} Sort by CNK code "ASC" or "DESC" {"cnk": "ASC"} or {"cnk": "DESC"}
{"createdAt": ...} Sort by created time "ASC" or "DESC" {"createdAt": "ASC"} or {"createdAt": "DESC"}
{"touchedAt": ...} Sort by last updated time "ASC" or "DESC" {"touchedAt": "ASC"} or {"touchedAt": "DESC"}
{"statusTouchedAt": ...} Sort by last time status was updated "ASC" or "DESC" {"statusTouchedAt": "ASC"} or {"statusTouchedAt": "DESC"}
{"status": ...} Sort by product status "ASC" or "DESC" {"status": "ASC"} or {"status": "DESC"}

Tip

The maximum amount of identifier codes provided cannot exceed 1000.
If your query contains more than 1000, please break it down into multiple requests with smaller sets.

Response

Body

Note

The maximum number is limited to 10000; use the stream endpoint to get all results

  • meta:
    • total: total number of products across all pages. (integer)
    • page:
      • no: page number (zero-based) (integer)
      • offset: offset of the first product in the entire result set (integer)
      • size: size of the page (integer)
  • results[]: a list of matching products on this page.
    • id: Medipim ID of the product (string, unique)
    • status: Product status ( active, inactive, replaced, no_selection )
    • ecommerce: (⚠️ field is not used anymore)
    • replacement: Medipim ID of the replacing product (only in case product status is "replaced") (string)
    • name.{...}: Name (string, localized)
    • seoName.{...}: SEO friendly name (string, localized)
    • shortDescription.{...}: Short description (string, localized)  (⚠️ field is not used anymore)
    • prescription: Whether the product requires a prescription. (boolean)
    • writtenRequestByPatient: Written request by patient. (boolean)
    • requiresLegalText: Product requires a legal text (description) to be displayed. (boolean)
    • narcotic: Product is a narcotic drug.(boolean)
    • biocide: Product is a biocide.(boolean)
    • officialDeletionAt: Official commercial end date of the product. (unix timestamp)
    • ean[]: EAN codes (integer[])
    • gtin: GTIN code (string) (⚠️ deprecated use eanGtin14 instead)
    • eanGtin8: EAN8 code (integer with exactly 8 digits, might start with leading zeros)
    • eanGtin12: EAN12 code (integer with exactly 12 digits, might start with leading zeros)
    • eanGtin13: EAN13 code (integer with exactly 13 digits, might start with leading zeros)
    • eanGtin14: EAN14 / GTIN code (integer with exactly 14 digits, might start with leading zeros)
    • supplierReference: The internal reference code that a company gives to a product (string)
    • hsCode: Harmonised System (HS) code (integer)
    • cnk: CNK code (string)
    • udi: UDI code (string)
    • nut: NUT code (string)
    • ctiExtended: Extended CTI code (string)
    • nameCti: Grouping by name (nameCti) code (string)
    • conservationLabel: Description of the type of conservation.
    • conservationMin: Minimum value for the temperature of the type of conservation. This will be in Celsius, Fahrenheit and Kelvin.
    • conservationMax: Maximum value for the temperature of the type of conservation. This will be in Celsius, Fahrenheit and Kelvin.
    • conservation: Conservation for a given product. Possible values: room, refrigerator, fresh, frozen (string)
    • vat: rate of VAT (float)
    • publicPrice: Public price (integer, in €)  (⚠️value is including VAT)
    • manufacturerPrice: Manufacturer price (integer, in € )  (⚠️value is excluding VAT)
    • pharmacistPrice: Pharmacist price (integer, in € )  (⚠️value is excluding VAT)
    • refundValueWithOmnio: Refund value with Omnio status (integer, in €)  (⚠️value is including VAT)
    • refundValueWithoutOmnio: Refund value without Omnio status (integer, in €)  (⚠️value is including VAT)
    • weight: Weight (integer, in grams) (⚠️ deprecated use weightWithUnit instead)
    • weightWithUnit: Weight(object)
      • value: value (integer)
      • unit: unit (string)
    • width: Width (integer, in millimeters) (⚠️ deprecated use widthWithUnit instead)
    • widthWithUnit: Length(object)
      • value: value (integer)
      • unit: unit (string)
    • length: Length (integer, in millimeters) (⚠️ deprecated use lengthWithUnit instead)
    • lengthWithUnit: Length(object)
      • value: value (integer)
      • unit: unit (string)
    • depth: Depth (integer, in millimeters) (⚠️ deprecated use depthWithUnit instead)
    • depthWithUnit: Length(object)
      • value: value (integer)
      • unit: unit (string)
    • packageContent: Package Content (string)
    • packageQuantity: Package Quantity (integer)
    • packagingUnit: Packaging unit (string)
    • atc: ATC code (string) (⚠️ deprecated use atcCategory instead)
    • atcCategory[]: List of ATC category codes associated with this product (string[])
    • notApplicableField[]: List of fields that are not applicable to the product(string[])
    • publicCategories[]: A collection of public categories this product belongs to. | GET /v4/public-categories/query response
      • id: ID of the category (integer)
      • name.{...}: Name of the category (string, localized)
      • parent: ID of the parent category (integer)
      • meta:
        • createdAt: When the category was created on Medipim (unix timestamp)
        • updatedAt: When the category information was last updated (unix timestamp)
    • apbCategory[]: APB categories this product belongs to (if any)
      • id: ID of the category (string, unique)
      • name.{...}: Name of the category (string, localized)
    • bcfiCategory[]: BCFI categories this product belongs to (if any) | GET /v4/bcfi-categories/query response
      • id: ID of the category (string, unique)
      • parent: ID of the parent category (string)
      • order: Sort order of the category (integer)
      • name.{...}: Name of the category (string, localized)
      • meta:
        • createdAt: When the category was created on Medipim (unix timestamp)
        • updatedAt: When the category information was last updated (unix timestamp)
    • supplyProblems[]: Supply problems for this product (if any)
      • fromDate: The start date of the supply problem (unix timestamp)
      • endDate: Expected availability date of the product with a supply problem (unix timestamp)
      • reason: The reason of the supply problem (string)
      • impact: Impact of the supply problem (string, optional)
    • endOfCommercializationData: End of commercialization data for this product (if any)
      • fromDate: The start date of the end of commercialization (unix timestamp)
      • expectedEndDate: Expected date when product would be commercially available again(unix timestamp, optional)
      • status: The status of the end of commercialization (string, optional)
      • reason: The reason of the end of commercialization (string, optional)
      • impact: Impact of the end of commercialization (string, optional)
    • brands[]: A collection of brands associated with this product. | POST /v4/brands/query response
      • id: ID of the brand (integer)
      • name.{...}: Name of the brand (string, localized)
      • meta:
        • createdAt: When the brand was created on Medipim (unix timestamp)
        • updatedAt: when the brand information was last updated (unix timestamp)
    • productFamilies[]: A collection of product families associated with this product. | POST /v4/product-families/query response
      • id: ID of the product family (integer)
      • name.{...}: Name of the product family (string, localized)
      • meta:
        • createdAt: When the product family was created on Medipim (unix timestamp)
        • updatedAt: when the product family information was last updated (unix timestamp)
    • attributes[]: A collection of attribute values associated with this product. | POST /v4/product/attribute/options/query
      • id: Medipim ID of the option (integer)
      • type: Code of the attribute (string)
      • name.{...}: Name of option (string, localized)
      • meta:
        • createdAt: When the option was created on Medipim (unix timestamp)
        • updatedAt: when the option information was last updated (unix timestamp)
    • organizations[]: A collection of organizations associated with this product. | POST /v4/organizations/query response
      • id: ID of the organization (integer, unique)
      • name.{...}: Name of the organization (string, localized)
      • type: type of the organization "supplier", "marketing", "medical_professional", "other" )
      • meta:
        • createdAt: When the organization information was created on Medipim (unix timestamp)
        • updatedAt: When the organization information was last updated (unix timestamp)
      • contactInformation: Only available when the organisation type equals supplier.
        • address: Street address of the organization (string, optional)
        • zipCode: Zip code of the city (string, optional)
        • region: Name of the region (string, optional)
        • city: Name of the city (string, optional)
        • country: ISO2 code of the country where the organization is located (string, optional)
        • url: Url of organization website (string, optional)
    • activeIngredients[]: A collection of active ingredients associated with this product | GET /v4/active-ingredients/query response
      • id: ID of the active ingredient (integer, unique)
      • name.{...}: Name of the active ingredient (string, localized)
      • meta:
        • createdAt: When the active ingredient was created on Medipim (unix timestamp)
        • updatedAt: When the active ingredients was last updated (unix timestamp)
    • photos[]: A collection of photos associated with this product. (same as media query results)
      • locales[]: List of languages for which this media is suited. (string[])
      • targetGroups[]: List of target groups for which this media is suited. (string[])
      • photoType: Type of photo "packshot", "productshot", "lifestyle_image", "pillshot" )
      • formats[]: List of available image formats
        • thumbnail: Media url for the thumbnail image format of the photo. 200x200 pixels. (string)
        • thumbnailWebp: Media url for the thumbnail image format of the photo. 200x200 pixels. (string)
        • huge: Media url for the huge image format of the photo. 1500x1500 pixels. (string)
        • hugeWebp: Media url for the huge image format of the photo. 1500x1500 pixels. Webp variant. (string)
        • large: Media url for the large image format of the photo. 900x900 pixels. (string)
        • largeWebp: Media url for the large image format of the photo. 900x900 pixels. Webp variant. (string)
        • medium: Media url for the medium image format of the photo. 450x450 pixels. (string)
        • mediumWebp: Media url for the medium image format of the photo. 450x450 pixels. Webp variant. (string)
      • visibleSides[]: Visible sides of the photo (string)
      • meta:
        • createdAt: When the brand was created on Medipim (unix timestamp)
        • updatedAt: When the brand information was last updated (unix timestamp)
      • organizations[]: List of organizations the photo is linked to.
      • name.{...}: Name (string, localized)
    • frontals[]: A sub-collection of frontal photos associated with this product. (same as media query results)
      • photoType: Type of photo "packshot", "productshot"
      • formats[]: List of available image formats
        • thumbnail: Media url for the thumbnail image format of the photo. 200x200 pixels. (string)
        • thumbnailWebp: Media url for the thumbnail image format of the photo. 200x200 pixels. (string)
        • medium: Media url for the medium image format of the photo. 450x450 pixels. (string)
        • mediumJpeg: Media url for the medium image format of the photo. 450x450 pixels. (string)
        • mediumWebp: Media url for the medium image format of the photo. 450x450 pixels. Webp variant. (string)
        • largeJpg: Media url for the large image format of the photo. 900x900 pixels. (string)
        • largeWebp: Media url for the large image format of the photo. 900x900 pixels. Webp variant. (string)
        • huge: Media url for the huge image format of the photo. 1500x1500 pixels. (string)
        • hugeWebp: Media url for the huge image format of the photo. 1500x1500 pixels. Webp variant. (string)
    • links[]: A collection of media links associated with this product. (same as media query results)
    • descriptions[]: A collection of descriptions for this product.
      • id: ID of the description. (integer, unique)
      • locales[]: Languages for which this description is suitable. (string[])
      • targetGroups[]: Target groups for which this description is suitable. (string[])
      • type: Type of description. (string)
      • content.{...}: Description content (string, localized)
      • meta:
        • createdAt: When the description was created on Medipim (unix timestamp)
        • updatedAt: When the description was last updated (unix timestamp)
    • leaflets[]: A collection of leaflets for this product.
      • id: ID of the leaflet (integer, unique)
      • locales[]: Languages for which the leaflet is suitable.
      • type: Type of leaflet ( "pil", "spc" )
      • url.{...}: Urls of the leaflet (string, localized)
      • meta:
        • createdAt: When the leaflet was added on Medipim (unix timestamp)
        • updatedAt: When the leaflet was last updated (unix timestamp)
    • meta:
      • createdAt: When the product was added to Medipim. (unix timestamp)
      • updatedAt: The last time the product was modified (includes modifications to photos, links, ...). (unix timestamp)
      • embedUrl: A pre-signed link to the embed endpoint for this product. Note that this URL is only valid a few hours. (string)

The same media item (photos, frontals and links) can be linked to multiple products

Tip

If no images are available in the language you need, we advise to use the following fallbacks:

  • for NL: try 'fr', then 'en', then other locales
  • for FR: try 'nl', then 'en', then other locales
  • for EN: try 'nl', then other locales

Examples