> ## Documentation Index
> Fetch the complete documentation index at: https://developer.worldly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MSI Search Materials

## 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.

<Card title="MSI - Get all material data" icon="book-open" href="/recipes/get-all-materials">View recipe</Card>

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](/data-dictionary/msi#materialtrimpackage-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.

```json Search parameters theme={null}
{
  "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](/data-dictionary/msi#materialtrimpackage-metadata) for details about each parameter.

```json Metadata results theme={null}
{
    "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](/data-dictionary/msi#impacts) for details about each impact parameter.

```json Aggregate impacts theme={null}
"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](/data-dictionary/msi#category-base-materials-and-processes) 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.

<Note>
  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.
</Note>

<Card title="MSI - Get all material data" icon="book-open" href="/recipes/get-all-materials">View recipe</Card>

```json Base material impacts theme={null}
"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.

```json Yield results theme={null}
"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.

```json Search for User Updates theme={null}
{
    "platformModifiedBy": "User",
    "lastEditedAfter": "2021-01-13T16:38:19.386Z",
    "lastEditedBefore": "2021-12-13T20:38:19.386Z"
}
```


## OpenAPI

````yaml api-reference/openapi/msi-api.json POST /search
openapi: 3.0.0
info:
  title: msi-api
  version: 1.0.0
servers:
  - url: https://api-v2.production.higg.org/msi-api/v1
    description: Production
  - url: https://api-v2.demo.higg.org/msi-api/v1
    description: Demo
security:
  - sec0: []
    sec1: []
paths:
  /search:
    post:
      operationId: Search
      requestBody:
        $ref: '#/components/requestBodies/MsiEntityRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsiEntityResponse'
components:
  requestBodies:
    MsiEntityRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MsiEntityRequest'
      required: true
  schemas:
    MsiEntityResponse:
      properties:
        from:
          type: number
          format: double
        size:
          type: number
          format: double
        total:
          type: number
          format: double
        results:
          items:
            $ref: '#/components/schemas/MsiEntityResult'
          type: array
      required:
        - from
        - results
        - size
        - total
      type: object
      additionalProperties: false
    MsiEntityRequest:
      properties:
        ids:
          items:
            type: string
          type: array
          nullable: true
        code:
          items:
            type: string
          type: array
          nullable: true
        name:
          type: string
          nullable: true
        text:
          type: string
          nullable: true
        draft:
          type: boolean
          nullable: true
        sample:
          type: boolean
          nullable: true
        type:
          $ref: '#/components/schemas/MsiEntityType'
        createdAfter:
          type: string
          format: date-time
          nullable: true
        createdBefore:
          type: string
          format: date-time
          nullable: true
        lastEditedAfter:
          type: string
          format: date-time
          nullable: true
        lastEditedBefore:
          type: string
          format: date-time
          nullable: true
        platformModifiedBy:
          $ref: '#/components/schemas/PlatformDefault'
        platformCreatedBy:
          $ref: '#/components/schemas/PlatformDefault'
        from:
          type: number
          format: double
          nullable: true
        size:
          type: number
          format: double
          nullable: true
      type: object
      additionalProperties: false
    MsiEntityResult:
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/MsiEntityType'
        sample:
          type: boolean
        draft:
          type: boolean
        created:
          type: number
          format: double
        lastEdited:
          type: number
          format: double
        name:
          type: string
        code:
          type: string
          nullable: true
        partNumber:
          type: string
          nullable: true
        productNumber:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        vendor:
          type: string
          nullable: true
        platformCreatedBy:
          $ref: '#/components/schemas/PlatformDefault'
        platformModifiedBy:
          $ref: '#/components/schemas/PlatformDefault'
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialEntityOptionalProcess'
          type: array
          nullable: true
        userEmail:
          type: string
        sharedBy:
          $ref: '#/components/schemas/MsiSharedBy'
        description:
          type: string
          nullable: true
        scores:
          $ref: '#/components/schemas/MsiImpactScoresResult'
        yieldInfo:
          items:
            $ref: '#/components/schemas/ApiMSiYieldInfo'
          type: array
          nullable: true
      required:
        - created
        - draft
        - id
        - lastEdited
        - name
        - sample
        - scores
        - type
        - userEmail
      type: object
      additionalProperties: false
    MsiEntityType:
      enum:
        - material
        - trim
        - packaging
      type: string
    PlatformDefault:
      enum:
        - User
        - Api
      type: string
    BaseMaterialEntityOptionalProcess:
      properties:
        cycles:
          $ref: '#/components/schemas/MateriaCycle'
      type: object
      additionalProperties: false
    MsiSharedBy:
      properties:
        accountName:
          type: string
        accountId:
          type: string
        sacId:
          type: number
          format: double
        oarId:
          type: string
          nullable: true
        taxId:
          type: string
          nullable: true
        customIds:
          properties: {}
          additionalProperties:
            type: string
          type: object
      required:
        - accountId
        - accountName
        - customIds
        - sacId
      type: object
      additionalProperties: false
    MsiImpactScoresResult:
      properties:
        impact:
          type: number
          format: double
          nullable: true
      type: object
      additionalProperties: false
    ApiMSiYieldInfo:
      properties:
        type:
          $ref: '#/components/schemas/YieldType'
        width:
          type: number
          format: double
          nullable: true
        widthUnit:
          $ref: '#/components/schemas/YieldWidth'
        thickness:
          type: number
          format: double
          nullable: true
        thicknessUnit:
          $ref: '#/components/schemas/YieldThickness'
        densityLinear:
          type: number
          format: double
          nullable: true
        densityLinearUnit:
          $ref: '#/components/schemas/YieldDensityLinear'
        densityVolumetric:
          type: number
          format: double
          nullable: true
        densityVolumetricUnit:
          $ref: '#/components/schemas/YieldDensityVolumetric'
        conversion:
          type: number
          format: double
      required:
        - conversion
        - type
      type: object
      additionalProperties: false
    MateriaCycle:
      properties: {}
      type: object
      additionalProperties:
        $ref: '#/components/schemas/MaterialCycleResult'
    YieldType:
      enum:
        - Yards (linear)
        - Meters (linear)
        - Feet (linear)
        - Square Yards (linear)
        - Square Meters (linear)
        - Square Feet (linear)
        - Yards (volumetric)
        - Meters (volumetric)
        - Feet (volumetric)
        - Square Yards (volumetric)
        - Square Meters (volumetric)
        - Square Feet (volumetric)
      type: string
    YieldWidth:
      enum:
        - m
        - yd
        - in
        - cm
      type: string
    YieldThickness:
      enum:
        - in
        - cm
        - mm
      type: string
    YieldDensityLinear:
      enum:
        - g/m2
        - kg/m2
        - lb/yd2
        - oz/yd2
      type: string
    YieldDensityVolumetric:
      enum:
        - kg/m3
        - lb/ft3
      type: string
    MaterialCycleResult:
      properties:
        processes:
          items:
            type: string
          type: array
        selected:
          items:
            $ref: '#/components/schemas/MaterialSelectedProcess'
          type: array
        allowNone:
          type: boolean
        multi:
          type: boolean
        scores:
          $ref: '#/components/schemas/MsiImpactScores'
        detailProcesses:
          items:
            $ref: '#/components/schemas/DetailProcesses'
          type: array
          nullable: true
        stageName:
          type: string
          nullable: true
      required:
        - allowNone
        - multi
        - processes
        - scores
        - selected
      type: object
      additionalProperties: false
    MaterialSelectedProcess:
      properties:
        id:
          type: string
        applyToWholeMaterial:
          type: boolean
          nullable: true
        lossRate:
          type: number
          format: double
          nullable: true
        defectRate:
          type: number
          format: double
          nullable: true
        transportDistance:
          type: number
          format: double
          nullable: true
        transportDistanceUnit:
          $ref: '#/components/schemas/MsiTransportationUnit'
        transportationMode:
          $ref: '#/components/schemas/MsiTransportationMode'
        rawMaterialChemCerts:
          items:
            $ref: '#/components/schemas/RawMaterialChemCert'
          type: array
          nullable: true
        facilityChemCerts:
          items:
            $ref: '#/components/schemas/FacilityChemCert'
          type: array
          nullable: true
        scores:
          $ref: '#/components/schemas/MsiImpactScores'
      required:
        - id
        - scores
      type: object
      additionalProperties: false
    MsiImpactScores:
      properties:
        globalWarming:
          type: number
          format: double
        eutrophication:
          type: number
          format: double
        waterScarcity:
          type: number
          format: double
        abioticDepletion:
          type: number
          format: double
        chemistry:
          type: number
          format: double
        globalWarmingPts:
          type: number
          format: double
        eutrophicationPts:
          type: number
          format: double
        waterScarcityPts:
          type: number
          format: double
        abioticDepletionPts:
          type: number
          format: double
        impact:
          type: number
          format: double
        chemistryPts:
          type: number
          format: double
        waterConsumption:
          type: number
          format: double
        biogenicCarbon:
          type: number
          format: double
      required:
        - abioticDepletion
        - abioticDepletionPts
        - biogenicCarbon
        - chemistry
        - chemistryPts
        - eutrophication
        - eutrophicationPts
        - globalWarming
        - globalWarmingPts
        - impact
        - waterConsumption
        - waterScarcity
        - waterScarcityPts
      type: object
      additionalProperties: false
    DetailProcesses:
      properties:
        name:
          type: string
        id:
          type: string
      required:
        - id
        - name
      type: object
      additionalProperties: false
    MsiTransportationUnit:
      enum:
        - km
        - miles
      type: string
    MsiTransportationMode:
      enum:
        - truck
        - ocean
        - rail
        - air
      type: string
    RawMaterialChemCert:
      enum:
        - betterCottonInitiativeMaterial
        - grsMaterial
        - cradleToCradleMaterial
      type: string
    FacilityChemCert:
      enum:
        - oekoTexStepLevel2Facility
        - grsFacility
      type: string
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: x-api-key
    sec1:
      type: apiKey
      in: header
      name: x-developer-request-token

````