INCI Explainer Integration on Website

Last updated January 9, 2023

Once you have signed up for the INCI Explainer you will receive your INCI Explainer code or JSON Endpoint Information from your Skin Match Technology Project Manager.

Java Script Snippet Setup & Integration

While you are waiting for your code, make sure you have sent us the following:
- EAN Excel List with your full inventory
- Data Feed to automatically detect inventory changes
- A list of all domains the INCI Explainer needs to run on (Including the Development and Testing Environment)

Once you have received the code, copy the code provided. It will look something like this:

<div id="smt-inci-5060389245893"></div> <script defer async
src="https://inciexplainer.skinmatchapp.com/?
id=YOURIDXXX&ean=5060389245893&lang=en"></script>

This is the JavaScript Snippet. You place it wherever you want and it will load the ingredient list with the explainer functionality.

  • You don’t need to have an ingredient list for a product. We have them on our end and they will be loaded by the snippet. You simply have to provide the EAN as a URL parameter on the snippet so that we know which ingredient list to load. In the example code above it is the number 5060389245893. You can see that it is requested twice.

  • You don’t have to worry about ingredient list formatting. We have the ingredients saved in our database and will output them always in the same way.

  • You don’t have to submit anything else to us in order for the snippet to work. There is no API necessary or anything like that.

  • It is literally just placing the div + script and that’s all there is to it.

Optionally you can then write some custom CSS to overwrite the look of the INCI Explainer. You can read more about it here.

Related Topics

For the INCI Explainer to work we will need:

  1. An Excel list of your inventory providing us with EAN, Brand, Product Title, Size or Variant.

  2. A complete list of your domains that we should allow the INCI Explainer to be displayed. Please include Stage or Development environment domains. 

Send the above to your Skin Match Technology representative or questions@skin-match.com

JSON Endpoint Setup & Integration

While you are waiting for your JSON Endpoint, make sure you have sent us the following:
- EAN Excel List with your full inventory
- Data Feed to automatically detect inventory changes
- A list of all domains the INCI Explainer needs to run on (Including the Development and Testing Environment)

Once you have received the JSON Endpoint, it will look something like this:

https://provided_domain.com/json.php?id=YOURIDXXXX&ean=9340800000369

The JSON Endpoint is a URL that we will provide you. You can send an HTTP request to with the specific EAN, for the product you want INCI Explainer Data for, and it will return JSON that is related to the request you sent.

You then parse the returned JSON (into the structure of whatever programming language you are using) so you can then use the returned data in your own code. See an example of the returned data below:

[{"inci_name":"AQUA","inci_id":"2120","chemical_name":"Water","inci_name_readable":"Water","explainer":{"source":["Sourced from a naturally occuring source"],"function":["Can have the following uses in cosmetics: Solvent"],"utility":[],"effect":["Can have a moisturizing\/hydrating effect on your skin."],"group":[]}},

{"inci_name":"BENTONITE","inci_id":"2988","chemical_name":"Bentonite. A colloidal clay. Consists primarily of montmorillonite (CI 77004)","inci_name_readable":"BENTONITE","explainer":{"source":["Sourced from minerals"],"function":["Can have the following uses in cosmetics: Absorbent, Bulking, Emulsion Stabilising, Viscosity Controlling"],"utility":["Used as an emulsifier to homogeneously mix ingredients."],"effect":["Can have an anti-acne effect."],"group":[]}},

{"inci_name":"KAOLIN","inci_id":"12817","chemical_name":"Naturally occurring substances, kaolin (CI 77004)","inci_name_readable":"KAOLIN","explainer":{"source":["Sourced from minerals"],"function":["Can have the following uses in cosmetics: Abrasive, Absorbent, Anticaking, Bulking, Cosmetic Colourant, Opacifying"],"utility":["Can be used to give products its color."],"effect":[],"group":["Is an aluminum."]}},

We deliver the following data within the JSON for each INCI per Product (EAN request)

  • INCI Name: Official INCI Name in the order it should appear in the Ingredient list

  • Chemical Name: Alternative Chemical Name

  • INCI Name Readable: Alternative Name that is easily understandable by everyone (if applicable) For Example Bees Wax for Cera Alba or Water for Aqua.

  • Source: Where is this INCI sourced from. Some INCI can be sourced from various sources. We recommend showing all possible sources.

  • Function: A list of uses an INCI can have within a product formulation.

  • Utility: A longer description of possible usages in a formulation or to provide products its benefits.

  • Effect: Description of any effect an ingredient may have on the skin.

  • Group: Description of a known group an INCI may be part of

We do not always have data on all fields. We recommend only showing the specific field if data is delivered.

INCI Explainer Legal Disclaimer

Within the JavaScript Snippet, we display the following legal disclaimer to make sure users understand the information delivered as explanations for the specific ingredients and not the product formulation.

“All information below describes only this specific ingredient and its possible effects, utilities and sources. Usage and effect of the ingredient may differ per formulation of each product.”

We recommend adding this if you are building your own front end when using the JSON Endpoint for integration.

Additionally, we recommend to every beauty e-commerce store to add the following or similar disclaimer to their page.

“The ingredients list and details are provided for information purposes only. Formulation and ingredients are subject to change by the brand. Please refer to the product packaging for the most up-to-date ingredients list and be aware that it may change or vary from time to time. For any concerns please seek professional advice before use.”

EAN and SKU Lookup

A minimal API facilitates the look-up of whether an EAN or SKU is available within the context of the INCI Explainer. The API accepts either an EAN or SKU and will return a JSON with the status code, as well as setting the same status code within the HTTP header. Thus, to check the API response, it is possible to look either at the returned JSON or simply at the HTTP status code. 

Base-URL

https://inciexplainer-eanlookup.skinmatchapp.com

Allowed API Calls

/ean/{ean} ​>https://inciexplainer-eanlookup.skinmatchapp.com/ean/5060033778654

/sku/{sku} ​>https://inciexplainer-eanlookup.skinmatchapp.com​/sku/11203018

Response Codes & Descriptions

200 ​–  A status of 200 indicates that the EAN/SKU is available within the INCI Explainer.

204​ ​– The request was accepted but the requested API endpoint could not be found. This response will only be returned if the API could not locate the desired endpoint. For example, calling /upc/{upc} would result in a 204 status code as the endpoint does not fall within the allowed API calls.

400 ​– The request is missing crucial information. A status code 400 will be returned if your API call does not include an EAN/SKU and

404​ – Not found – A status code of 404 will be returned whenever the requested EAN/SKU is not available within the context of the INCI Explainer. Depending on the circumstance, the accompanying status message will give further information, e.g. “​The requested SKU is not available​” (SKU was found in the database but the associated product is currently missing ingredient data), “​The requested SKU could not be resolved to an EAN”​ (SKU was found in the database but is not associated with an EAN), or “​The requested SKU could not be found​” (SKU could not be found in the Database).

NOTE

EAN will internally be formatted to the EAN-13 format. Any EAN passed to the system with less than 13 digits will be padded with leading zeros.

Example Response: