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

## Introduction

This API endpoint allows for the creation of custom materials in the Higg MSI.

To create a custom material, the following base attributes are required:

* Name (open text field, must be unique within an MSI library)
* Category (user defined from the set of categories available in the MSI). See [MSI Get Material Categories](/api-reference/product-tools/msi-api-full/get-material-categories) for additional information.
* At least one base material (user defined from the set of base materials available in the MSI) See [MSI Get Base Materials](/api-reference/product-tools/msi-api-full/get-base-materials) for additional information.

An optional text field material code can be added as 'code'.  This field can be used to store a PLM id. Note that the field is editable by users within MSI.

```json Example minimal material creation theme={null}
{
    "name": "My custom material",
    "code": "my PLM code",
    "category": "TX",
    "baseMaterials":[{
        "baseMaterialId": "FM002"
    }]
}
```

## Creating blends

Blends are based on % of material for 1kg of MSI material.  For example the code below represents an MSI material with 60% organic cotton, 40% polyester.  The % blend must equal 100%.

```json Example blended material creation theme={null}
{

    "name": "Organic/Poly Blend",
    "code": "my PLM code",
    "baseMaterials":[{
        "baseMaterialId": "TX0010",
        "blendPercentage": 60
    }, {
        "baseMaterialId": "TX0001",
        "blendPercentage": 40
    }],
      "category": "TX"
}
```

## Setting Yields

Optionally one or multiple yields can be sent for a material.  All materials in MSI are normalized to 1kg.  Yields provide conversions for the MSI 1kg material to a linear/volumetric unit. See [MSI Get Yield Options](/api-reference/product-tools/msi-api-full/get-yield-options) for additional information.

```json Example blend material with yield creation theme={null}
{
    "name": "Example MSI custom material",
    "code": "yield 2",
    "baseMaterials": [
        {
            "baseMaterialId": "FM002"
        }
    ],
    "yieldInfo": [
        {
            "type": "Yards (volumetric)",
            "width": 1,
            "widthUnit": "m",
            "thickness": 2,
            "thicknessUnit": "in",
            "densityVolumetric": 13,
            "densityVolumetricUnit": "kg/m3"
        }
    ],
    "category": "TX"
}
```

## Setting Base Material Processes

The stage process for a base material can be changed via the API using the `processId`.  For example, changing 'cotton, fiber' to 'cotton fiber, organic" in the raw material formation stage.  The processes must be available for the base material to change it. See [MSI Get Processes for Base Material](/api-reference/product-tools/msi-api-full/get-processes) for how to get a list of available processes and their IDs.

```json Example material creation with specific process theme={null}
{
    "name": "Test blend",
    "code": "xyz PLM code",
    "baseMaterials":[{
        "baseMaterialId": "FM002",
        "blendPercentage": 60,
        "processes": {
      	 "P001": "PR0804000648",
         "P002": "PR0804000331"
        }
    }, {
    	 "baseMaterialId": "TX0010",
       "blendPercentage": 40,
       "processes": {
       	"P006": "PR0804000543"
       }
   }],
      "category": "TX"
}
```

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


## OpenAPI

````yaml api-reference/openapi/msi-api.json POST /materials/create
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/create:
    post:
      operationId: CreateMaterial
      requestBody:
        $ref: '#/components/requestBodies/CreateMaterialApi'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaterialEntityWithoutProcess'
components:
  requestBodies:
    CreateMaterialApi:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateMaterialApi'
      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
    CreateMaterialApi:
      properties:
        name:
          type: string
        code:
          type: string
          nullable: true
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialProcessId'
          type: array
        yieldInfo:
          items:
            $ref: '#/components/schemas/YieldInfo'
          type: array
          nullable: true
        category:
          type: string
      required:
        - baseMaterials
        - category
        - name
      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
    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
    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
    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

````