Medipim API V3

Developer documentation

POST /v3/products/search

Request

Method

POST

URL

https://api.medipim.be/v3/products/search

Headers

Body

  • filter: one of the filters below; filters can be combined using and, or & not. (required)
  • sorting: one of the sortings below. (optional; default is {"id": "ASC"})
  • page:
    • no: page number (zero-based)
    • size: one of 10, 50, 100 or 250 (defaults to 100)
Filter Description Parameters Examples
{"id": ...} Matches products by Medipim ID. One or more Medipim ID(s) {"id": "M12345ABCD"} or {"id":["M12345ABCD", "M54321DCBA"]}
{"cnk": ...} Matches products by CNK. One or more CNKs {"cnk": "4444444"} or {"cnk": ["1234567", "4444444"]}
{"status": ...} Matches products by status. One or more product statuses.
Possible values: `"active"`, `"replaced"` or `"inactive"`.		 {"status": "active"} or {"status": ["replaced", "inactive"]}
{"ecommerce": ...} Matches products by ecommerce status. One or more ecommerce statuses.
Possible values: `"yes"`, `"no"` or `"unknown"`.		 {"ecommerce": "yes"} or {"ecommerce": ["yes", "unknown"]}
{"apbCategory": ...} Matches products by APB category. One or more APB category IDs. {"apbCategory":"homeopathy"} or {"apbCategory": ["material", "reactive"]}
{"conservation": ...} Matches products by conservation. One or more conservation types. {"conservation":"room"} or {"conservation": ["room", "frozen", ...]}
{"publicCategory": ...} Matches products by public category. One or more public category IDs. {"publicCategory": 12} or {"publicCategory": [3, 6]}
{"bcfiCategory": ...} Matches products by BCFI category. One or BCFI category IDs. {"bcfiCategory": "0017566"} or {"bcfiCategory": ["0017566", "0000976"]}
{"productFamily": ...} Matches products by Product Family Association Identifier. One or Product family association IDs. {"productFamily": "0017566"} or {"productFamily": ["0017566", "0000976"]}
{"brand": ...} Matches products by brand. One or more brand IDs. {"brand": 4} or {"brand": [14, 3]}
{"organization": ...} Matches products by organization. One or more organization IDs. {"organization": 2} or {"organization": [2, 15]}
{"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}
{"minimumContent": ...} Matches products that have at least one photo or one description. true or false. {"minimumContent": true} or {"minimumContent": false}
{"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}}
{"cti": ...} Matches products with specified CTI number. String. {"cti": "240904"}
{"ean": ...} Matches products with specified EAN number. String. {"ean": "3574660696318"} or {"ean": ["3574660696318", "3401526293056", ...]}
{"gtin": ...} Matches products with specified GTIN number. String. {"gtin": "03664798014846"} or {"gtin": ["03664798014846", "07613326014816", ...]}
{"activeIngredient": ...} Matches products by active ingredients. One or more activeIngredient IDs. {"activeIngredient": [1, 2]}
{"search": ...} Matches products by a specific search query. Array with 'query' and 'locale' key. {"search": {"query": "test", "locale": "nl"}}
{"and": [...]} Matches products that match all of 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"}
{"cnk": ...} Sort by CNK "ASC" or "DESC" {"cnk": "ASC"} or {"cnk": "DESC"}

Tip

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

Response

Body

  • meta
    • total: total results across all pages. (The maximum number is limited to 10000; use the export endpoint to get all results)
    • page
      • no: page number (zero-based)
      • offset: offset of the first product in the entire resultset
      • size: size of the page
  • results[]: a list of matching products on this page.
    • id: Medipim ID (integer, unique)
    • status: Product status ("active", "replaced" or "inactive")
    • ecommerce: Whether a product can be sold online or not ("yes", "no" or "unknown")
    • replacement: Medipim ID of the replacing product (only in case product status is "replaced")
    • name.{nl|fr|en}: Name (string, localized)
    • seoName.{nl|fr|...}: SEO friendly name (string, localized)
    • shortDescription.{nl|fr|en|...}: Short description (string, localized). (⚠️ field is not used anymore)
    • prescription: Whether or not the product requires a prescription. (boolean)
    • writtenRequestByPatient: Written request by patient. (boolean)
    • officialDeletionAt: Official date on which the product became unavailable. (timestamp)
    • cnk: CNK code (⚠️ not every product has a CNK) (string)
    • ean[]: EAN codes (⚠️ a product may have multiple EAN codes)
    • udi: UDI code
    • nut: NUT code
    • atc: ATC code (string) (⚠️ deprecated use atcCategory instead)
    • atcCategory[]: List of ATC category codes associated with this product (string[])
    • ctiExtended: Extended CTI code
    • conservation: Conservation for a given product. (string) Possible values: room, refrigerator, fresh, frozen
    • publicPrice: Public price (integer, in EUR cents) (⚠️value is including VAT)
    • pharmacistPrice: Pharmacist price (integer, in EUR cents) (⚠️value is excluding VAT)
    • vat: rate of VAT (float)
    • refundValueWithOmnio: Refund value with Omnio status (⚠️value is including VAT)
    • refundValueWithoutOmnio: Refund value without Omnio status (⚠️value is including VAT)
    • weight: Weight (integer, in grams)
    • width: Width (integer, in millimeters)
    • length: Length (integer, in millimeters)
    • depth: Depth (integer, in millimeters)
    • packageQuantity: Package Quantity
    • bcfiCategory: BCFI category this product belongs to (if any) | GET /v3/bci-categories/all response
      • id: ID of the category (string)
      • parent: ID of the parent category (string)
      • order: Sort order of the category (int)
      • name.{nl|fr|en}: name of the category (string, localized)
      • meta
        • createdAt: When the category was created on Medipim (unix timestamp)
        • updatedAt: When the category was last updated (unix timestamp)
    • apbCategory: APB category this product belongs to (if any) | GET /v3/apb-categories/all response
      • id: ID of the category (string)
      • name.{nl|fr|en}: name of the category (string, localized)
    • publicCategories[]: A collection of public categories this product belongs to. | GET /v3/public-categories/all response
      • id: ID of the category (integer, unique)
      • name.{nl|fr|en}: 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)
    • brands[]: A collection of brands associated with this product. | GET /v3/brands/all response
      • id: ID of the brand (integer, unique)
      • name.{nl|fr|en}: 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)
    • organizations[]: A collection of organizations associated with this product. | GET /v3/organizations/all response
      • id: ID of the organization (integer, unique)
      • name.{nl|fr|en}: Name of the organization (string, localized)
      • type: type of the organization (supplier or marketing)
      • meta
        • createdAt: When the organization information was created on Medipim (unix timestamp)
        • updatedAt: When the organization information was last updated (unix timestamp)
    • attributes[]: A collection of attributes associated with this product. | GET /v3/attributes/all response
      • id: ID of the attribute (integer, unique)
      • name.{nl|fr|en}: Name of the attribute (string, localized)
      • meta
        • createdAt: When the attribute information was created on Medipim (unix timestamp)
        • updatedAt: When the attribute information was last updated (unix timestamp)
    • activeIngredients[]: A collection of active ingredients associated with this product | GET /v3/active-ingredients/all response
      • id: ID of the active ingredient (integer, unique)
      • name.{nl|fr|en}: 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. The same photo may be linked to multiple products.
      • id: ID of the photo (integer, unique)
      • locales[]: Languages for which the photo is suitable.

        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
      • targetGroups[]: Target groups for which this photo is suitable. (public, pharmacist, doctor, homecare or hospital)
      • type: Type of photo ("packshot", "productshot", "pillshot" or "lifestyle_image")
      • formats:
        • huge: Media url for the huge image format of the photo (string)
        • large: Media url for the large image format of the photo (string)
        • medium: Media url for the medium image format of the photo (string)
      • meta
        • createdAt: When the photo was created on Medipim (unix timestamp)
        • updatedAt: When the photo was last updated (unix timestamp)
    • frontals[]: A collection of frontal photos associated with this product.
    • links[]: A collection of media links associated with this product.
      • id: ID of the media link (integer, unique)
      • locales[]: Languages for which this media link is suitable.
      • targetGroups[]: Target groups for which this media link is suitable. (public, pharmacist, doctor, homecare or hospital)
      • type: Type of the media link (app, brochure, video or website)
      • url: The url of the media link (string)
      • name.{nl|fr|en}: Name of the media link (string, localized)
      • description.{nl|fr|en}: Description of the media link (string, localized)
      • available
        • from: When the media link is available from (unix timestamp)
        • until: When the media link expires (unix timestamp)
      • meta
        • createdAt: When the media link was created on Medipim (unix timstamp)
        • updatedAt: When the media link was last updated (unix timestamp)
    • descriptions[]: A collection of descriptions for this product.
      • id: ID of the description. (integer, unique)
      • locales[]: Languages for which this description is suitable.
      • targetGroups[]: Target groups for which this description is suitable. (public, pharmacist, doctor, homecare or hospital)
      • type: Type of description. (full_description, indication, contra_indication, usage, composition or properties)
      • content.{nl|fr|en}: Description content (localized)
        • html: In HTML format.
        • markdown: In Markdown format (⚠️Will become deprecated starting july 2018)
      • 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 or spc)
      • url.{nl|fr|en}: 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: Product metadata
      • 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)

Examples