> ## 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 Update Materials

## Updating Custom Materials

The MSI API provides functionality to update custom materials via the API.  Note it is not currently possible to update custom trims or packaging via that API.  The API returns the material Higg ID and impacts in the response.

See [MSI Data Dictionary](/data-dictionary/msi#materialtrimpackage-metadata) for details about the parameters.

The API uses the custom material id to identify the material to update.  The user can then optionally send the following information to update the material.  Only the parameters sent via the update are updated.

The user can update:
• material name
• material code
• custom material category
• base material, % composition for blends, and raw material process stage
• yield

<Warning>
  Note that updating any of base material, % composition for blends, raw material process stage and yield completely overwrites the previously entered base materials. For example, if the original material was 80% organic cotton/20% polyester, then sending 100% cotton fiber will change the material to 100% cotton fiber.
</Warning>

```json Updating material theme={null}
{
    "name": "Test blend",
    "code": "xyz PLM code",
    "baseMaterials":[{
        "baseMaterialId": "FM002",
        "processId": "PR0804000648",
        "blendPercentage": 60
    }, {
        "baseMaterialId": "FM005",
        "blendPercentage": 40
    }],
    "yieldInfo": [
        {
            "type": "Yards (volumetric)",
            "width": 1,
            "widthUnit": "m",
            "thickness": 2,
            "thicknessUnit": "in",
            "densityVolumetric": 13,
            "densityVolumetricUnit": "kg/m3"
        }
    ],
    "category": "TX"
}
```

## Finding materials modified by user

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 /materials/update/{materialId}
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:
  /materials/update/{materialId}:
    post:
      operationId: UpdateMaterial
      parameters:
        - in: path
          name: materialId
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/UpdateMaterialApi'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaterialEntityWithoutProcess'
components:
  requestBodies:
    UpdateMaterialApi:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateMaterialApi'
      required: true
  schemas:
    MaterialEntityWithoutProcess:
      properties:
        _id:
          type: string
        _rev:
          type: string
          nullable: true
        type:
          type: string
        user:
          $ref: '#/components/schemas/UserRef'
        account:
          $ref: '#/components/schemas/AccountRef'
        created_on:
          type: number
          format: double
        last_edit:
          type: number
          format: double
          nullable: true
        category:
          type: string
        version:
          $ref: '#/components/schemas/MaterialVersionWithoutProcess'
        history:
          items:
            $ref: '#/components/schemas/MaterialVersionWithoutProcess'
          type: array
          nullable: true
        sharedBy:
          $ref: '#/components/schemas/MaterialShare'
        image:
          type: string
          nullable: true
        draft:
          type: boolean
        platformModifiedBy:
          $ref: '#/components/schemas/PlatformDefault'
        platformCreatedBy:
          $ref: '#/components/schemas/PlatformDefault'
        deleted:
          type: boolean
          nullable: true
        lastEditedBy:
          $ref: '#/components/schemas/UserRef'
        deletedBy:
          $ref: '#/components/schemas/UserRef'
      required:
        - _id
        - account
        - category
        - created_on
        - draft
        - type
        - user
        - version
      type: object
      additionalProperties: false
    UpdateMaterialApi:
      properties:
        name:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        yieldInfo:
          items:
            $ref: '#/components/schemas/YieldInfo'
          type: array
          nullable: true
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialProcessId'
          type: array
          nullable: true
        category:
          type: string
          nullable: true
      type: object
      additionalProperties: false
    UserRef:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "userRef".
      properties:
        _id:
          type: string
        email:
          type: string
        firstname:
          type: string
          nullable: true
        lastname:
          type: string
          nullable: true
      required:
        - _id
        - email
      type: object
      additionalProperties: false
    AccountRef:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "accountRef".
      properties:
        _id:
          type: string
        name:
          type: string
        country:
          type: string
        sacId:
          type: number
          format: double
        oar_id:
          type: string
          nullable: true
        demoaccount:
          type: boolean
          nullable: true
        vbType:
          $ref: '#/components/schemas/AccountVbType'
        socialCreditId:
          type: string
          nullable: true
        taxId:
          type: string
          nullable: true
        bluesignId:
          type: string
          nullable: true
        zdhcId:
          type: string
          nullable: true
        ipeViolation:
          $ref: '#/components/schemas/IpeViolationRef'
        ffcId:
          type: number
          format: double
          nullable: true
        approvalStatus:
          $ref: '#/components/schemas/AccountApprovalStatus'
      required:
        - _id
        - country
        - name
        - sacId
      type: object
      additionalProperties: false
    MaterialVersionWithoutProcess:
      properties:
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialEntityOptionalProcess'
          type: array
      required:
        - baseMaterials
      type: object
      additionalProperties: false
    MaterialShare:
      properties:
        materialId:
          type: string
        materialVersion:
          type: string
        date:
          type: number
          format: double
        sendingUser:
          $ref: '#/components/schemas/UserRef'
        sendingAccount:
          $ref: '#/components/schemas/AccountRef'
        status:
          $ref: '#/components/schemas/MaterialShareStatus'
        comment:
          type: string
          nullable: true
      required:
        - date
        - materialId
        - materialVersion
        - sendingAccount
        - sendingUser
        - status
      type: object
      additionalProperties: false
    PlatformDefault:
      enum:
        - User
        - Api
      type: string
    YieldInfo:
      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'
      required:
        - type
      type: object
      additionalProperties: false
    BaseMaterialProcessId:
      properties:
        blendPercentage:
          type: number
          format: double
          nullable: true
        baseMaterialId:
          type: string
        processes:
          properties: {}
          additionalProperties:
            type: string
          type: object
          nullable: true
      required:
        - baseMaterialId
      type: object
      additionalProperties: false
    AccountVbType:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "accountVbType".
      enum:
        - None
        - 2nd Party
        - 3rd Party
      type: string
    IpeViolationRef:
      properties:
        totalViolations:
          type: number
          format: double
      required:
        - totalViolations
      type: object
      additionalProperties: false
    AccountApprovalStatus:
      enum:
        - Approved
        - Declined
        - New
      type: string
    BaseMaterialEntityOptionalProcess:
      properties:
        cycles:
          $ref: '#/components/schemas/MateriaCycle'
      type: object
      additionalProperties: false
    MaterialShareStatus:
      enum:
        - pending
        - accepted
        - rejected
      type: string
    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
    MateriaCycle:
      properties: {}
      type: object
      additionalProperties:
        $ref: '#/components/schemas/MaterialCycleResult'
    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

````