Common data formats

Several data structures appear across multiple endpoints in the Medipim API. This page documents each of them so you can interpret responses and construct requests correctly.

Languages and localized fields

Some fields in the API — such as product names, descriptions, and category labels — are localized, meaning they can have a different value per language. The supported languages for your region are: es,en.

Localized fields are returned as a JSON object keyed by locale code:

{
  "name": {
    "nl": "Paracetamol 500mg",
    "fr": "Paracétamol 500mg",
    "en": "Paracetamol 500mg",
    "de": "Paracetamol 500mg"
  }
}

The object always contains all supported locales as keys. If a translation is not available for a given locale, the value will be null or an empty string.

Target groups

Product descriptions and media items (photos, frontals, and links) are scoped by target group. A target group represents a specific audience — this allows the same product to carry different descriptions and images depending on who is viewing it. For example, a pharmacist-targeted description may contain dosage and active ingredient details, while the public version focuses on general usage information.

In API responses, descriptions and media items include a targetGroups array listing the audiences the content is intended for. A single description or media item can belong to multiple target groups. The API returns only the content that matches the target groups your organization has access to — which target groups you can see depends on your subscription. Most integrators work with the public target group.

The available target groups are:

Target group	Audience
public	General public and consumers
pharmacist	Licensed pharmacists
doctor	Medical doctors
nurse	Nursing professionals
physiotherapist	Physiotherapists
hospital	Hospital staff and procurement
homecare	Home care providers
webshop	E-commerce and webshop integrations

Product identifier codes

Products on Medipim can be identified by several code systems. The following identifiers are enforced as unique on the Spain region.

Code	Description
cn	Código Nacional — national code for pharmaceutical products.
eanGtin8	8-digit Global Trade Item Number.
eanGtin12	12-digit GTIN, typically used in the US and Canada.
eanGtin13	13-digit GTIN, typically used outside the US and Canada.
eanGtin14	14-digit GTIN.

Discover available fields

Use the get-product-fields endpoint to see which identifier codes and other fields are available in your region.

Product CTI code

The CTI (Common Technical Identifier) groups products where the product is identical except for the quantity or packaging — for example, a box of 20 tablets and a box of 50 tablets of the same medicine share the same CTI code.

CTI appears as two fields on a product response:

• cti — the base CTI code identifying the product group.
• ctiExtended — a more specific variant that includes additional detail (e.g. packaging differentiation).

You can also use cti as a filter to retrieve all products in the same group.

Grouping by name (nameCti)

The nameCti field (shown as group by product name on the platform) groups products whose name is identical except for the quantity indication. Like CTI, it lets you collapse different packaging variants of the same product into a single group — but the grouping is derived from the product name rather than from a curated code.

Name quality affects grouping

Medipim collects product names from various sources. Poorly structured or inconsistent names can lead to discrepancies in how products are grouped by nameCti.

You can also use nameCti as a filter to retrieve all products that share the same name group. Because names are localized, the filter takes both a value and a locale:

{
  "nameCti": {
    "value": "603722",
    "locale": "en"
  }
}

Product descriptions

A product can have multiple descriptions, each with a different purpose. In the API response, each description is an object with the following key fields:

• type — the description type, indicating what kind of content this is (e.g. full_description, usage, composition). See the table below for all types.
• descriptionTag — indicates who generated the content: user_generated (entered by the organization), system_generated (from an automated data source), or ai_generated (produced by AI).
• targetGroups — which audiences this description is intended for (see Target groups above). A product can have different descriptions of the same type for different target groups.
• content — the localized text, keyed by locale (see Languages above).
• locales — which languages have content for this description.

Description types

Type	Description
full_description	The main product description covering general information, features, and benefits.
indication	Medical or therapeutic indications — what the product is used for.
contra_indication	Conditions or situations where the product should not be used.
usage	Instructions on how to use the product (dosage, application method, frequency).
usage_extended	Extended usage instructions with additional detail beyond the standard usage field.
usage_type	The type or method of use (e.g. oral, topical, injectable).
composition	The ingredients or active substances that make up the product.
properties	Key properties and characteristics of the product.
side_effects	Known side effects or adverse reactions.
interactions	Information about interactions with other medicines or substances.
warnings	General warnings and precautions for use.
pregnancy_description	Warnings and guidance specific to use during pregnancy.
breastfeeding_description	Warnings and guidance specific to use while breastfeeding.
nutritional_value	Nutritional information (relevant for food supplements and dietary products).
measurements	Physical dimensions or size information.
legal_text	Legally required text (e.g. regulatory notices, disclaimers).
faq	Frequently asked questions about the product.
keywords	Search keywords associated with the product.

HTML content

Some text fields (such as product descriptions) may contain HTML markup. Only a limited set of HTML tags is allowed — any tags not listed below are stripped from the content.

Tag	Allowed attributes
<b>	—
<i>	—
<p>	style
<table>	style, border
<tbody>	—
<thead>	—
<tfoot>	—
<tr>	—
<th>	style, colspan, rowspan
<td>	style, colspan, rowspan
<ol>	—
<ul>	—
<li>	—
<span>	style
<strong>	—
<em>	—
<div>	class, style
<h1> through <h6>	—
<dl>	—
<dt>	—
<dd>	—
<blockquote>	—
<sup>	—
<sub>	—

When displaying description content in your application, make sure your rendering layer supports these tags. If you need plain text, strip the HTML tags on your side.

Country regions

Organizations on Medipim (specifically suppliers) can be associated with a country region — a geographic subdivision within the platform's country. These are based on the ISO 3166-2 standard, which defines codes for provinces, states, and other subdivisions (e.g. BE-BRU for Brussels, BE-VLG for Flanders, FR-IDF for Île-de-France).

Country region codes appear in the contactInformation.region field of organization responses. The set of valid codes depends on the platform region. See the organization endpoint documentation for details.

Filtering on available content (hasContent)

The hasContent filter selects only the products that actually have a value for a given field. It is an effective way to refine a selection so you don't process products that are missing the data you need. For example, to retrieve only products that have a weight:

{
  "hasContent": {
    "flag": "weight"
  }
}

hasContent can be combined with the and, or, and not compound filters. Use the get-product-fields endpoint to retrieve the list of flags you can filter on.

For localized fields, add a locale parameter to check whether content exists in a specific language:

{
  "hasContent": {
    "flag": "descriptions.usage",
    "locale": "en"
  }
}

For descriptions, you can also restrict the check to who generated the content by prefixing the flag with a description tag (user_generated, system_generated, or ai_generated):

{
  "hasContent": {
    "flag": "user_generated.descriptions.usage",
    "locale": "en"
  }
}

See the Worked examples page for hasContent combined with other filters.

Numerical operators

Some filters compare a numeric field against a value using a numerical operator. The operator goes in the filter's operator key alongside a numeric value. If operator is omitted, it defaults to eq.

The possible operators are:

Operator	Meaning
eq	Equal to
neq	Not equal to
lt	Less than
lte	Less than or equal to
gt	Greater than
gte	Greater than or equal to

For example, to filter products whose public price is greater than or equal to a value:

{
  "publicPrice": {
    "value": 1000,
    "operator": "gte"
  }
}