Skip to main content
POST
/
search
cURL
curl --request POST \
  --url https://api-v2.production.higg.org/msi-api/v1/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-developer-request-token: <api-key>' \
  --data '
{
  "ids": [
    "<string>"
  ],
  "code": [
    "<string>"
  ],
  "name": "<string>",
  "text": "<string>",
  "draft": true,
  "sample": true,
  "type": "material",
  "createdAfter": "2023-11-07T05:31:56Z",
  "createdBefore": "2023-11-07T05:31:56Z",
  "lastEditedAfter": "2023-11-07T05:31:56Z",
  "lastEditedBefore": "2023-11-07T05:31:56Z",
  "platformModifiedBy": "User",
  "platformCreatedBy": "User",
  "from": 123,
  "size": 123
}
'
{
  "from": 123,
  "size": 123,
  "total": 123,
  "results": [
    {
      "id": "<string>",
      "type": "material",
      "sample": true,
      "draft": true,
      "created": 123,
      "lastEdited": 123,
      "name": "<string>",
      "userEmail": "<string>",
      "scores": {
        "impact": 123
      },
      "code": "<string>",
      "partNumber": "<string>",
      "productNumber": "<string>",
      "category": "<string>",
      "vendor": "<string>",
      "platformCreatedBy": "User",
      "platformModifiedBy": "User",
      "baseMaterials": [
        {
          "cycles": {}
        }
      ],
      "sharedBy": {
        "accountName": "<string>",
        "accountId": "<string>",
        "sacId": 123,
        "customIds": {},
        "oarId": "<string>",
        "taxId": "<string>"
      },
      "description": "<string>",
      "yieldInfo": [
        {
          "type": "Yards (linear)",
          "conversion": 123,
          "width": 123,
          "widthUnit": "m",
          "thickness": 123,
          "thicknessUnit": "in",
          "densityLinear": 123,
          "densityLinearUnit": "g/m2",
          "densityVolumetric": 123,
          "densityVolumetricUnit": "kg/m3"
        }
      ]
    }
  ]
}

​
Introduction

The Higg MSI API is a JSON query API. All parameters are sent as JSON. The search endpoint can be used to download the full account dataset for processing in the third-party system, or the endpoint can be queried on a number of useful parameters to bring back impacts for specific materials.

​
Search Parameters

To return all data in the account, remove all the search parameters and use {}. All data including example materials/trims/packages will be returned.

Get all data for all materials

View recipe
The following attributes can be used to query the endpoint. The materials/trims/packaging that meet all entered criteria will be returned. See MSI Data Dictionary—Metadata for details about each search parameter. To control the number of results returned and loop through the materials, you can use the from and size fields. The ‘from’ field tells the system which position to pull from. Note that the system starts at position 0. The ‘size’ determines how many materials to return.
Search parameters
{
  "ids": [
    "string"
  ],
  "code": [
    "string"
  ],
  "name": "string",
  "text": "string",
  "draft": true,
  "sample": true,
  "type": "material",
  "createdAfter": 0,
  "createdBefore": 0,
  "lastEditedAfter": 0,
  "lastEditedBefore": 0,
  "platformCreatedBy":"string",
  "platformModifiedBy":"string",
  "from": 0,
  "size": 0
}

​
Search Results

Extensive information about the material, trim, and package is returned via the Search functionality. The data returned includes: • Number of results and their location • Metadata about the material such as who and when it was created/edited. • Aggregate impacts • Process-level impacts for materials • Yield conversions

​
Metadata Results

Metadata about the material, trim, package are returned. See MSI Data Dictionary Metadata for details about each parameter.
Metadata results
{
    "from": 0,
    "size": 1,
    "total": 1,
    "results": [
        {
            "id": "611ffbcc908bc0000a82df78",
            "type": "material",
            "sample": false,
            "draft": false,
            "created": 1629486028720,
            "lastEdited": 1629486028720,
            "name": "Yield Aug 20",
            "code": "yield3",
            "userEmail": "jane.doe@higg.com",
            "platformModifiedBy": "User",
            "platformCreatedBy": "User",

​
Impacts

Impacts include both Higg MSI normalized scores and Life Cycle Impact Assessment (LCIA) absolute values. The following impacts are included in the Higg MSI API for all example materials, custom materials, acquired materials, sample trims and components, custom trims and components, sample packaging, and custom packaging. Aggregate and material process-level impacts are returned: • Global Warming MSI Score • Global Warming LCIA value (kg CO2 eq) • Eutrophication MSI Score • Eutrophication LCIA value (kg PO4– eq) • Water Scarcity MSI Score • Water Scarcity LCIA value (m3) • Abiotic Resource Depletion, Fossil Fuels MSI Score • Abiotic Resource Depletion, Fossil Fuels LCIA value (MJ eq) • Chemistry MSI Score • Chemistry LCIA value (units) • Biogenic Carbon Content LCIA value (kg CO2 eq) • Water Consumption LCIA value (liters) • MSI total single score [This score is no longer available in the Higg MSI API as of January 2021] See MSI Data Dictionary Impacts for details about each impact parameter.
Aggregate impacts
"scores": {
                "globalWarming": 15.114249119474671,
                "eutrophication": 0.006025696080364703,
                "waterScarcity": 2.971424237136378,
                "abioticDepletion": 252.60178650939986,
                "chemistry": 19.926823592866178,
                "globalWarmingPts": 14.258782619312404,
                "eutrophicationPts": 6.316243274738611,
                "waterScarcityPts": 1.3630517260591994,
                "abioticDepletionPts": 17.300696358028794,
                "chemistryPts": 9.443919505367068,
                "waterConsumption": 81.65567784773765,
                "biogenicCarbon": 0
            }

​
Category, Base Materials and Processes

See the MSI Data Dictionary for details about each parameter. Category Category is the material category (Textiles, Leathers, etc). The ‘category’ associated with the baseMaterials result is a system defined material type and is not editable. The custom material category returned at the end of the results, is a user-defined attribute that can be set via the API and does not impact any other features about the material it is helpful for categorizing and filtering. Base Materials/Example Materials Base materials (which are also the Example Materials) are the top-level type of material. Base Materials are then customized by process cycles/stages (eg cycles/stages are raw material stage, textile formation, dying etc). Cycles Cycles are the process stages users select to customize materials. The base material uses the default raw material cycle/stage process (for example cotton, fabric can be the base material). The raw material cycle/stage process for the base material can be changed via the API using the processId. For example, changing default ‘cotton, fabric’ to ‘cotton fiber, organic”. The processes must be available for the base material in order to select them. The user can also change additional processes manually in the Higg MSI tool.
By default only the full material and base material impacts are returned via that API. If you would like to retrieve the additional cycle process information for each material, use the API header “show-api-fields”=True.

Get all data for all materials

View recipe
Base material impacts
"baseMaterials": [
                {
                    "_id": "TX0010",
                    "name": "Cotton fabric",
                    "code": "TX0010",
                    "category": "TX",
                    "blendPercentage": 100,
                    "scores": {
                        "globalWarming": 6.981835590562421,
                        "eutrophication": 0.005401301586885609,
                        "waterScarcity": 4.662750835068845,
                        "abioticDepletion": 84.55144285473486,
                        "chemistry": 17.513598264341564,
                        "globalWarmingPts": 6.586663696136588,
                        "eutrophicationPts": 5.661741708841108,
                        "waterScarcityPts": 2.138897063062781,
                        "abioticDepletionPts": 5.7909283211207905,
                        "chemistryPts": 8.300219625419398,
                        "impact": 28.478450414580667,
                        "waterConsumption": 113.09555183103872,
                        "biogenicCarbon": 0.6277194375332535
                    },
                    "type": "BaseMaterial",
                    "finishedMaterialChemCertsAvailable": [
                        "bluesignCertified",
                        "cradleToCradleGoldCertified",
                        "gotsCertified",
                        "grsCertified",
                        "oekoTextMadeInGreenCertified",
                        "oekoTextStandard100Certified"
                    ],
                    "categoryRanking": 0.8260869565217391
                },

​
Yield

Yield is returned for materials where the user provided yield for the material.
Yield results
"yieldInfo": [
                {
                    "type": "Yards (linear)",
                    "densityLinear": 3,
                    "densityLinearUnit": "g/m2",
                    "width": 2,
                    "widthUnit": "m",
                    "conversion": 0.0054864
                }
            ]

​
Searching for materials manually updated in MSI

A common use case is to search for materials that have been manually updated by a user in MSI, in order to pull the updated material impacts into the PLM. Users can search for “PlatformModifiedBy”: “User” to find materials updated by users directly in MSI. The “lastEditedAfter”: 0 and “lastEditedBefore”: 0 search parameters can be used to set the date period to search for edits.
Search for User Updates
{
    "platformModifiedBy": "User",
    "lastEditedAfter": "2021-01-13T16:38:19.386Z",
    "lastEditedBefore": "2021-12-13T20:38:19.386Z"
}

Authorizations

​
x-api-key
string
header
required
​
x-developer-request-token
string
header
required

Body

application/json
​
ids
string[] | null
​
code
string[] | null
​
name
string | null
​
text
string | null
​
draft
boolean | null
​
sample
boolean | null
​
type
enum<string>
Available options:
material,
trim,
packaging
​
createdAfter
string<date-time> | null
​
createdBefore
string<date-time> | null
​
lastEditedAfter
string<date-time> | null
​
lastEditedBefore
string<date-time> | null
​
platformModifiedBy
enum<string>
Available options:
User,
Api
​
platformCreatedBy
enum<string>
Available options:
User,
Api
​
from
number<double> | null
​
size
number<double> | null

Response

200 - application/json

Ok

​
from
number<double>
required
​
size
number<double>
required
​
total
number<double>
required
​
results
object[]
required