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

# Create Material

Use this endpoint to create a custom material in your PIC material library. Custom materials let you model Tier 2 and Tier 3 supply chain processes by specifying base materials, life cycle stages, and facility-level environmental data.

<Card title="PIC | Create a Material with T2/T3 Links" href="/recipes/pic-create-material-t2t3" />

### Request body params

| Name                               | Type                  | Description                                                                                                                                                                        |
| :--------------------------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                             | `string`              | **\[REQUIRED]** The name for your custom material.                                                                                                                                 |
| `cycleProcess`                     | `Array<CycleProcess>` | **\[REQUIRED]** Life cycle processes for this material (stages P002–P006).                                                                                                         |
| `cycleProcess[].lifeCycle`         | `string`              | **\[REQUIRED]** The life cycle stage ID (e.g., `"P002"` for Yarn Formation, `"P003"` for Fabric Formation).                                                                        |
| `baseMaterials`                    | `Array<BaseMaterial>` | **\[REQUIRED]** The base materials that compose this custom material.                                                                                                              |
| `baseMaterials[].id`               | `string`              | **\[REQUIRED]** The base material ID. Use [Get Base Materials](/api-reference/pic/material-library/get-base-materials) to find IDs.                                                |
| `baseMaterials[].composition`      | `number`              | **\[REQUIRED]** The percentage composition (all base materials must sum to 100%).                                                                                                  |
| `code`                             | `string`              | Optional material code.                                                                                                                                                            |
| `category`                         | `string`              | Optional material category.                                                                                                                                                        |
| `supplier`                         | `string`              | Optional supplier name.                                                                                                                                                            |
| `supplierCountry`                  | `string`              | Optional supplier country.                                                                                                                                                         |
| `country`                          | `string`              | Optional country of origin.                                                                                                                                                        |
| `cycleProcess[].country`           | `string`              | Country value for this process stage. Use [Get Country List](/api-reference/pic/material-library/get-countries) for valid values. Required if `facilityWorldlyId` is not provided. |
| `cycleProcess[].facilityWorldlyId` | `string`              | Worldly facility ID for facility-specific data. Use [Get Facilities](/api-reference/pic/material-library/get-facilities) to find available facilities.                             |
| `baseMaterials[].sustainability`   | `string \| null`      | Optional sustainability certification for this base material (e.g., `"recycled"`, `"organic"`). May be `null`.                                                                     |

### Implementation Details

* **Composition validation**: Base material compositions must sum to exactly 100%. This is a server-enforced constraint not expressed in the OpenAPI schema.
* **Life cycle stages**: Valid life cycle IDs are `P002` through `P006`. Each life cycle stage must be unique within a material. These are server-enforced constraints.
* **Location requirement**: Each life cycle process requires either a `country` or a `facilityWorldlyId` — at least one must be provided (server-enforced).
* **Sustainability values**: If provided, sustainability is a free-form string label (e.g., `"recycled"`, `"organic"`). It is optional and may be `null`.


## OpenAPI

````yaml api-reference/openapi/french-eco.json POST /material-library/create
openapi: 3.0.0
info:
  title: pic-api
  version: 1.0.0
servers:
  - url: https://api-v2.production.higg.org/pic-api/v1
    description: Production
  - url: https://api-v2.demo.higg.org/pic-api/v1
    description: Demo
security:
  - sec0: []
    sec1: []
paths:
  /material-library/create:
    post:
      summary: Create Material Library
      operationId: CreateMaterialLibrary
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMaterialLibraryApi'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PicMaterialLibraryEntity'
components:
  schemas:
    CreateMaterialLibraryApi:
      properties:
        name:
          type: string
        code:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        supplierCountry:
          type: string
          nullable: true
        supplier:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        cycleProcess:
          items:
            $ref: '#/components/schemas/CycleProcess'
          type: array
        baseMaterials:
          items:
            $ref: '#/components/schemas/MaterialLibraryBaseMaterialsRef'
          type: array
      required:
        - baseMaterials
        - cycleProcess
        - name
      type: object
      additionalProperties: false
    PicMaterialLibraryEntity:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "picMaterialLibraryEntity".
      properties:
        _id:
          type: string
        _rev:
          type: string
          nullable: true
        type:
          type: string
        name:
          type: string
        code:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        supplierCountry:
          type: string
          nullable: true
        nameId:
          type: string
          nullable: true
        supplier:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        t2GlobalWarmingImpact:
          type: number
          format: double
        t3GlobalWarmingImpact:
          type: number
          format: double
        t4GlobalWarmingImpact:
          type: number
          format: double
        tier2:
          $ref: '#/components/schemas/PicTier'
        tier3:
          $ref: '#/components/schemas/PicTier'
        baseMaterials:
          items:
            $ref: '#/components/schemas/PicBaseMaterialRef'
          type: array
          nullable: true
        createdOn:
          type: number
          format: double
        modifiedOn:
          type: number
          format: double
          nullable: true
        deleted:
          type: boolean
          nullable: true
        deletedBy:
          $ref: '#/components/schemas/UserRef'
        user:
          $ref: '#/components/schemas/UserRef'
        account:
          $ref: '#/components/schemas/AccountRef'
        modifiedBy:
          $ref: '#/components/schemas/UserRef'
        createdBy:
          $ref: '#/components/schemas/UserRef'
        totalMaterialGlobalWarmingImpact:
          type: number
          format: double
        v2Calculations:
          $ref: '#/components/schemas/V2Calculations'
        msiVersion:
          type: string
          nullable: true
        tags:
          items:
            type: string
          type: array
          nullable: true
      required:
        - _id
        - account
        - createdOn
        - name
        - t2GlobalWarmingImpact
        - t3GlobalWarmingImpact
        - t4GlobalWarmingImpact
        - totalMaterialGlobalWarmingImpact
        - type
        - user
      type: object
      additionalProperties: false
    CycleProcess:
      properties:
        lifeCycle:
          type: string
        country:
          type: string
          nullable: true
        facilityWorldlyId:
          type: string
          nullable: true
      required:
        - lifeCycle
      type: object
      additionalProperties: false
    MaterialLibraryBaseMaterialsRef:
      properties:
        id:
          type: string
        composition:
          type: number
          format: double
        sustainability:
          type: string
          nullable: true
        shortPath:
          $ref: '#/components/schemas/PicShortPath'
        manufacturer:
          type: string
          nullable: true
        tradeName:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        typeCode:
          type: string
          nullable: true
        materialSubtype:
          type: string
          nullable: true
        sustainabilityAttribute:
          type: string
          nullable: true
      required:
        - composition
        - id
      type: object
      additionalProperties: false
    PicTier:
      properties:
        isDefault:
          type: boolean
        assessment:
          $ref: '#/components/schemas/AssessmentMaterialRef'
        facility:
          $ref: '#/components/schemas/AccountRef'
        country:
          type: string
          nullable: true
        facilityRawText:
          type: string
          nullable: true
      required:
        - isDefault
      type: object
      additionalProperties: false
    PicBaseMaterialRef:
      properties:
        _id:
          type: string
        refKey:
          type: string
          description: >-
            Composite identity of this ref within the parent material's
            baseMaterials array. Format: '<_id>:<sustainabilityType|default>'.
            Optional for backward compatibility with legacy docs written before
            refKey existed (no migration planned).
          nullable: true
        composition:
          type: number
          format: double
        name:
          type: string
        sustainability:
          $ref: '#/components/schemas/PicSustainability'
        manufacturer:
          type: string
          description: >-
            Material-level filter: contributor / manufacturer selected for this
            base material. Constrains the matlibV2 activities resolution
            (contributor=).
          nullable: true
        tradeName:
          type: string
          description: >-
            Material-level filter: contributor trade name paired with the
            selected manufacturer.
          nullable: true
        country:
          type: string
          description: >-
            Material-level filter: country selected for this base material
            constituent.
          nullable: true
        typeCode:
          type: string
          description: >-
            Material-level filter: material type code (e.g. TX, BR) of this base
            material constituent.
          nullable: true
        materialSubtype:
          type: string
          description: >-
            Material-level filter: material subtype selected at P001 (the
            raw-material stage embedded in the material card). Constrains the
            matlibV2 P001 activity resolution.
          nullable: true
        sustainabilityAttribute:
          type: string
          description: >-
            Material-level filter: sustainability attribute selected at P001
            (per-material select). Sent at the component level in the matlibV2
            calculation request.
          nullable: true
        baseMaterialProcesses:
          items:
            $ref: '#/components/schemas/PicBaseMaterialProcessRef'
          type: array
          description: this field is responsible for using the default process
        baseMaterialProcessesList:
          items:
            $ref: '#/components/schemas/PicBaseMaterialProcessRef'
          type: array
          description: this field is responsible for using all processes
          nullable: true
        uniqueCyclesAssessments:
          items:
            $ref: '#/components/schemas/PicAssessmentUniqueCycles'
          type: array
          description: Total unique eligible cycles per assessment. P001 is not considered.
          nullable: true
        totalMaterialGlobalWarmingImpactT2:
          type: number
          format: double
        totalMaterialGlobalWarmingImpactT3:
          type: number
          format: double
        totalMaterialGlobalWarmingImpactT4:
          type: number
          format: double
        totalMaterialGlobalWarmingImpact:
          type: number
          format: double
        shortPath:
          $ref: '#/components/schemas/PicShortPath'
        v2Calculations:
          $ref: '#/components/schemas/V2Calculations'
        stages:
          items:
            $ref: '#/components/schemas/PicCalculateStageEntry'
          type: array
          description: >-
            Per-stage payload from matlibV2 the resolved process map for this
            base material.
          nullable: true
      required:
        - _id
        - baseMaterialProcesses
        - composition
        - name
        - totalMaterialGlobalWarmingImpact
        - totalMaterialGlobalWarmingImpactT2
        - totalMaterialGlobalWarmingImpactT3
        - totalMaterialGlobalWarmingImpactT4
      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
    V2Calculations:
      description: >-
        Calculation results produced by the matlibV2 calculator (POST
        /api/calculate). Carried at the material level on
        PicMaterialLibraryEntity and per-base-material on PicBaseMaterialRef so
        each scope's totals can be persisted alongside the v1 fields without
        disturbing them.
      properties:
        totalMaterialGlobalWarmingImpactT2:
          type: number
          format: double
          nullable: true
        totalMaterialGlobalWarmingImpactT3:
          type: number
          format: double
          nullable: true
        totalMaterialGlobalWarmingImpactT4:
          type: number
          format: double
          nullable: true
        totalMaterialGlobalWarmingImpact:
          type: number
          format: double
          nullable: true
      type: object
      additionalProperties: false
    PicShortPath:
      description: this field is responsible for using the default process
      properties:
        coatingLamination:
          $ref: '#/components/schemas/PicShortPathCoatingLamination'
        yarnSize:
          type: string
          description: Yarn Size
          nullable: true
        textileFormation:
          $ref: '#/components/schemas/PicShortPathTextileFormation'
        autoFromShortPath:
          type: boolean
          description: >-
            True when this base material ref was appended by the short-path
            coating logic; identifies the auto BR row for subsequent swap/remove
            operations.
          nullable: true
      type: object
      additionalProperties: false
    AssessmentMaterialRef:
      properties:
        _id:
          type: string
        rfi_pid:
          $ref: '#/components/schemas/AssessmentRfiPid'
        surveyVersion:
          type: string
        country:
          type: string
        processName:
          type: string
          description: 'some examples: yarnspinning, FacilityMaterialProcessTextiles'
      required:
        - _id
        - country
        - processName
        - rfi_pid
        - surveyVersion
      type: object
      additionalProperties: false
    PicSustainability:
      description: this field is responsible for using the default process
      properties:
        isEligible:
          type: boolean
        type:
          $ref: '#/components/schemas/PicMatLibSustainabilityEnum'
        processId:
          type: string
          description: Eligible recycled processId from P001
          nullable: true
      required:
        - isEligible
        - type
      type: object
      additionalProperties: false
    PicBaseMaterialProcessRef:
      properties:
        _id:
          type: string
        name:
          type: string
        stageName:
          type: string
        lifeCycle:
          type: string
        totalLossRate:
          type: number
          format: double
          description: total loss rate per cycle if process is eligible
          nullable: true
        residualElectricityTotal:
          type: number
          format: double
          description: total residual electricity per cycle if process is eligible
          nullable: true
        lossRate:
          type: number
          format: double
          description: process loss rate
          nullable: true
        assessment:
          $ref: '#/components/schemas/AssessmentMaterialRef'
        facility:
          $ref: '#/components/schemas/AccountRef'
        country:
          type: string
          nullable: true
        facilityType:
          items:
            type: string
          type: array
          nullable: true
        sipfacilitymaterialprocesstextiles:
          items:
            type: string
          type: array
          nullable: true
        materialproduction_normalized_kgco2e:
          type: number
          format: double
          nullable: true
        rawmaterialprocessing_normalized_kgco2e:
          type: number
          format: double
          nullable: true
        isEligible:
          type: boolean
        totalMaterialGlobalWarmingImpact:
          type: number
          format: double
        globalWarmingImpact:
          type: number
          format: double
          nullable: true
        ineligibleReason:
          $ref: '#/components/schemas/IneligibleReasonBaseMaterialProcess'
        femStatus:
          $ref: '#/components/schemas/AssessmentStatus'
        facilityRawText:
          type: string
          nullable: true
      required:
        - _id
        - isEligible
        - lifeCycle
        - name
        - stageName
        - totalMaterialGlobalWarmingImpact
      type: object
      additionalProperties: false
    PicAssessmentUniqueCycles:
      properties:
        assessmentId:
          type: string
        processId:
          type: string
        lifeCycle:
          type: string
        isEligible:
          type: boolean
        ineligibleReason:
          $ref: '#/components/schemas/IneligibleReasonBaseMaterialProcess'
        sipfacilitymaterialprocesstextiles:
          type: string
      required:
        - assessmentId
        - isEligible
        - lifeCycle
        - processId
        - sipfacilitymaterialprocesstextiles
      type: object
      additionalProperties: false
    PicCalculateStageEntry:
      description: >-
        Per-stage entry persisted on a PicBaseMaterialRef. Mirrors the higg.org
        FE's CalculateStageEntry shape — the same payload assembled for the
        Calculate Impact GW button. Persisting it lets us replay the user's
        exact selections without re-walking the cascade.
      properties:
        stageId:
          type: string
        processId:
          type: string
          nullable: true
        countryCode:
          type: string
        source:
          type: string
        lossRate:
          type: number
          format: double
          nullable: true
        residualGWP:
          type: number
          format: double
          nullable: true
        residualScope3GWP:
          type: number
          format: double
          nullable: true
        totalElectricity:
          type: number
          format: double
          nullable: true
        naturalGas:
          type: number
          format: double
          nullable: true
        diesel:
          type: number
          format: double
          nullable: true
        coal:
          type: number
          format: double
          nullable: true
        disaggregated:
          type: boolean
        systemBoundaryStages:
          items:
            type: string
          type: array
          nullable: true
        yarnSize:
          type: string
          nullable: true
        yarnUnit:
          type: string
          nullable: true
        countryGridEF:
          $ref: '#/components/schemas/PicCalculateStageCountryGridEF'
        formation:
          $ref: '#/components/schemas/PicShortPathTextileFormation'
        activityAttribute:
          type: string
          description: 'Activity filter: activity attribute (e.g. Yarn Texture).'
          nullable: true
        country:
          type: string
          description: 'Activity filter: country used to resolve the stage process.'
          nullable: true
        dyeType:
          type: string
          description: 'Activity filter: dye type.'
          nullable: true
        activityType:
          type: string
          description: 'Activity filter: activity type.'
          nullable: true
        processType:
          type: string
          description: 'Activity filter: process type (Default/Alternate).'
          nullable: true
        manufacturer:
          type: string
          description: 'Activity filter: manufacturer / MSI contributor name.'
          nullable: true
        textileFormation:
          type: string
          description: >-
            Activity filter: textile formation constraint passed to the matlibV2
            activities endpoint.
          nullable: true
        enabledBy:
          type: string
          description: >-
            Activity filter: upstream selection that enables this activity.
            Probably will not be used.
          nullable: true
        intrinsicCharacteristic:
          type: string
          description: 'Activity filter: intrinsic characteristic.'
          nullable: true
        layersCount:
          type: string
          description: 'Activity filter: number of layers (Barriers-specific).'
          nullable: true
        substratePURatio:
          type: string
          description: 'Activity filter: substrate PU ratio (Synthetic Leather-specific).'
          nullable: true
        programCertification:
          type: string
          description: 'Activity filter: program certification. Probably will not be used.'
          nullable: true
        inputFor:
          type: string
          description: >-
            Activity filter: downstream stage this activity is an input for.
            Probably will not be used.
          nullable: true
        contributor:
          type: string
          description: >-
            Activity filter: contributor used to resolve manufacturer-specific
            processes.
          nullable: true
        upstreamProcessId:
          type: string
          description: >-
            Activity filter: upstream process id; triggers the absorbed-stage
            early-return.
          nullable: true
        organizationId:
          type: string
          nullable: true
        approach:
          type: string
          nullable: true
        gwPerKg:
          type: number
          format: double
          nullable: true
        outputMass:
          type: number
          format: double
          nullable: true
        phaseGW:
          type: number
          format: double
          nullable: true
        transport:
          type: number
          format: double
          nullable: true
      required:
        - countryCode
        - disaggregated
        - source
        - stageId
      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
    PicShortPathCoatingLamination:
      description: Coating/Lamination
      enum:
        - Coating
        - Lamination
        - YesUnknown
      type: string
    PicShortPathTextileFormation:
      enum:
        - Knitting
        - Weaving
        - Non-Woven
      type: string
    AssessmentRfiPid:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "assessmentRfiPid".
      enum:
        - fem2017
        - fem2018
        - fem2019
        - fem2020
        - fem2021
        - fem2022
        - fem2023
        - fem2024
        - fem2025
        - fem2026
        - fslm
        - brm2019
        - brm2020
        - brm2021
        - brm2022
        - brm2023
        - brm2024
        - brm2025
        - dct
        - one2022
        - ffc
      type: string
    PicMatLibSustainabilityEnum:
      enum:
        - Recycled
        - Organic
      type: string
    IneligibleReasonBaseMaterialProcess:
      enum:
        - Fem not shared
        - Invalid Fem Module
        - Facility type not supported
        - Missing sipfacilitymaterialprocesstextiles
        - Missing Rawmaterialprocessing_normalized_kgco2e
        - Missing Materialproduction_normalized_kgco2e
        - Invalid sipfacilitymaterialprocesstextiles
        - Facility should be posted
        - >-
          Missing Rawmaterialprocessing_normalized_kgco2 or
          Materialproduction_normalized_kgco2e
      type: string
    AssessmentStatus:
      description: >-
        This interface was referenced by `Exports`'s JSON-Schema via the
        `definition` "assessmentStatus".
      enum:
        - NS
        - ASI
        - ASC
        - VRP
        - VRQ
        - VRE
        - VRC
        - VRD
        - VRF
        - VRI
        - ASD
      type: string
    PicCalculateStageCountryGridEF:
      description: >-
        Country-grid emission-factor block carried alongside each
        PicCalculateStageEntry. Mirrors the higg.org FE's
        CalculateStageEntry.countryGridEF.
      properties:
        countryCode:
          type: string
        gwp:
          type: number
          format: double
          nullable: true
        eutrophication:
          type: number
          format: double
          nullable: true
        waterScarcity:
          type: number
          format: double
          nullable: true
        abioticDepletion:
          type: number
          format: double
          nullable: true
        dataSource:
          type: string
          nullable: true
      required:
        - countryCode
      type: object
      additionalProperties: false
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: x-api-key
    sec1:
      type: apiKey
      in: header
      name: x-developer-request-token

````