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

# Get Materials

Use this endpoint to list and search the custom materials in your PIC material library. This returns materials that you have created or imported, not the default BOM catalog.

<Note>
  For the default BOM material catalog used when building product compositions, use [Get Materials (Product Attributes)](/api-reference/pic/product-attributes/get-materials) instead.
</Note>

### Implementation Details

* **Your materials only**: Returns materials belonging to your account's material library.
* **Searchable**: Supports text search and standard filtering parameters (skip, take, sort, filter) for advanced queries.


## OpenAPI

````yaml api-reference/openapi/french-eco.json POST /material-library/material-list
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/material-list:
    post:
      operationId: GetMaterialLibraryList
      requestBody:
        $ref: '#/components/requestBodies/SearchableKendoParams'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ESSearchCleanResponsePicMaterialLibraryEntity
components:
  requestBodies:
    SearchableKendoParams:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchableKendoParams'
      required: true
  schemas:
    ESSearchCleanResponsePicMaterialLibraryEntity:
      properties:
        total:
          type: number
          format: double
        max_score:
          type: number
          format: double
          nullable: true
        hits:
          items:
            $ref: '#/components/schemas/PicMaterialLibraryEntity'
          type: array
        aggregations:
          properties: {}
          additionalProperties:
            type: object
          type: object
          nullable: true
      required:
        - hits
        - total
      type: object
      additionalProperties: false
    SearchableKendoParams:
      properties:
        filter:
          $ref: '#/components/schemas/KendoFilter'
        skip:
          type: number
          format: double
          nullable: true
        take:
          type: number
          format: double
          nullable: true
        sort:
          items:
            $ref: '#/components/schemas/KendoSort'
          type: array
          nullable: true
        searchStr:
          type: string
          nullable: true
      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
    KendoFilter:
      properties:
        logic:
          type: string
          nullable: true
        filters:
          items:
            $ref: '#/components/schemas/KendoFilterFilter'
          type: array
          nullable: true
      type: object
      additionalProperties: false
    KendoSort:
      properties:
        field:
          type: string
        dir:
          type: string
          description: A sort lacking direction will be ignored
          nullable: true
        isNotNested:
          type: boolean
          nullable: true
      required:
        - field
      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
    KendoFilterFilter:
      properties:
        field:
          type: string
        operator:
          type: string
        value:
          type: object
      required:
        - field
        - operator
        - value
      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
    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
    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
    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
    PicShortPathCoatingLamination:
      description: Coating/Lamination
      enum:
        - Coating
        - Lamination
        - YesUnknown
      type: string
    PicShortPathTextileFormation:
      enum:
        - Knitting
        - Weaving
        - Non-Woven
      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

````