Skip to main content
POST
/
material-library
/
create
Create Material Library
curl --request POST \
  --url https://api-v2.production.higg.org/pic-api/v1/material-library/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-developer-request-token: <api-key>' \
  --data '
{
  "name": "<string>",
  "cycleProcess": [
    {
      "lifeCycle": "<string>",
      "country": "<string>",
      "facilityWorldlyId": "<string>"
    }
  ],
  "baseMaterials": [
    {
      "id": "<string>",
      "composition": 123,
      "sustainability": "<string>",
      "shortPath": {
        "yarnSize": "<string>",
        "autoFromShortPath": true
      },
      "manufacturer": "<string>",
      "tradeName": "<string>",
      "country": "<string>",
      "typeCode": "<string>",
      "materialSubtype": "<string>",
      "sustainabilityAttribute": "<string>"
    }
  ],
  "code": "<string>",
  "category": "<string>",
  "supplierCountry": "<string>",
  "supplier": "<string>",
  "country": "<string>"
}
'
import requests

url = "https://api-v2.production.higg.org/pic-api/v1/material-library/create"

payload = {
    "name": "<string>",
    "cycleProcess": [
        {
            "lifeCycle": "<string>",
            "country": "<string>",
            "facilityWorldlyId": "<string>"
        }
    ],
    "baseMaterials": [
        {
            "id": "<string>",
            "composition": 123,
            "sustainability": "<string>",
            "shortPath": {
                "yarnSize": "<string>",
                "autoFromShortPath": True
            },
            "manufacturer": "<string>",
            "tradeName": "<string>",
            "country": "<string>",
            "typeCode": "<string>",
            "materialSubtype": "<string>",
            "sustainabilityAttribute": "<string>"
        }
    ],
    "code": "<string>",
    "category": "<string>",
    "supplierCountry": "<string>",
    "supplier": "<string>",
    "country": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "x-developer-request-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'x-developer-request-token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    cycleProcess: [{lifeCycle: '<string>', country: '<string>', facilityWorldlyId: '<string>'}],
    baseMaterials: [
      {
        id: '<string>',
        composition: 123,
        sustainability: '<string>',
        shortPath: {yarnSize: '<string>', autoFromShortPath: true},
        manufacturer: '<string>',
        tradeName: '<string>',
        country: '<string>',
        typeCode: '<string>',
        materialSubtype: '<string>',
        sustainabilityAttribute: '<string>'
      }
    ],
    code: '<string>',
    category: '<string>',
    supplierCountry: '<string>',
    supplier: '<string>',
    country: '<string>'
  })
};

fetch('https://api-v2.production.higg.org/pic-api/v1/material-library/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-v2.production.higg.org/pic-api/v1/material-library/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'cycleProcess' => [
        [
                'lifeCycle' => '<string>',
                'country' => '<string>',
                'facilityWorldlyId' => '<string>'
        ]
    ],
    'baseMaterials' => [
        [
                'id' => '<string>',
                'composition' => 123,
                'sustainability' => '<string>',
                'shortPath' => [
                                'yarnSize' => '<string>',
                                'autoFromShortPath' => true
                ],
                'manufacturer' => '<string>',
                'tradeName' => '<string>',
                'country' => '<string>',
                'typeCode' => '<string>',
                'materialSubtype' => '<string>',
                'sustainabilityAttribute' => '<string>'
        ]
    ],
    'code' => '<string>',
    'category' => '<string>',
    'supplierCountry' => '<string>',
    'supplier' => '<string>',
    'country' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-developer-request-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-v2.production.higg.org/pic-api/v1/material-library/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"cycleProcess\": [\n    {\n      \"lifeCycle\": \"<string>\",\n      \"country\": \"<string>\",\n      \"facilityWorldlyId\": \"<string>\"\n    }\n  ],\n  \"baseMaterials\": [\n    {\n      \"id\": \"<string>\",\n      \"composition\": 123,\n      \"sustainability\": \"<string>\",\n      \"shortPath\": {\n        \"yarnSize\": \"<string>\",\n        \"autoFromShortPath\": true\n      },\n      \"manufacturer\": \"<string>\",\n      \"tradeName\": \"<string>\",\n      \"country\": \"<string>\",\n      \"typeCode\": \"<string>\",\n      \"materialSubtype\": \"<string>\",\n      \"sustainabilityAttribute\": \"<string>\"\n    }\n  ],\n  \"code\": \"<string>\",\n  \"category\": \"<string>\",\n  \"supplierCountry\": \"<string>\",\n  \"supplier\": \"<string>\",\n  \"country\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("x-developer-request-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api-v2.production.higg.org/pic-api/v1/material-library/create")
  .header("x-api-key", "<api-key>")
  .header("x-developer-request-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"cycleProcess\": [\n    {\n      \"lifeCycle\": \"<string>\",\n      \"country\": \"<string>\",\n      \"facilityWorldlyId\": \"<string>\"\n    }\n  ],\n  \"baseMaterials\": [\n    {\n      \"id\": \"<string>\",\n      \"composition\": 123,\n      \"sustainability\": \"<string>\",\n      \"shortPath\": {\n        \"yarnSize\": \"<string>\",\n        \"autoFromShortPath\": true\n      },\n      \"manufacturer\": \"<string>\",\n      \"tradeName\": \"<string>\",\n      \"country\": \"<string>\",\n      \"typeCode\": \"<string>\",\n      \"materialSubtype\": \"<string>\",\n      \"sustainabilityAttribute\": \"<string>\"\n    }\n  ],\n  \"code\": \"<string>\",\n  \"category\": \"<string>\",\n  \"supplierCountry\": \"<string>\",\n  \"supplier\": \"<string>\",\n  \"country\": \"<string>\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api-v2.production.higg.org/pic-api/v1/material-library/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-developer-request-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"cycleProcess\": [\n    {\n      \"lifeCycle\": \"<string>\",\n      \"country\": \"<string>\",\n      \"facilityWorldlyId\": \"<string>\"\n    }\n  ],\n  \"baseMaterials\": [\n    {\n      \"id\": \"<string>\",\n      \"composition\": 123,\n      \"sustainability\": \"<string>\",\n      \"shortPath\": {\n        \"yarnSize\": \"<string>\",\n        \"autoFromShortPath\": true\n      },\n      \"manufacturer\": \"<string>\",\n      \"tradeName\": \"<string>\",\n      \"country\": \"<string>\",\n      \"typeCode\": \"<string>\",\n      \"materialSubtype\": \"<string>\",\n      \"sustainabilityAttribute\": \"<string>\"\n    }\n  ],\n  \"code\": \"<string>\",\n  \"category\": \"<string>\",\n  \"supplierCountry\": \"<string>\",\n  \"supplier\": \"<string>\",\n  \"country\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "_id": "<string>",
  "type": "<string>",
  "name": "<string>",
  "t2GlobalWarmingImpact": 123,
  "t3GlobalWarmingImpact": 123,
  "t4GlobalWarmingImpact": 123,
  "createdOn": 123,
  "user": {
    "_id": "<string>",
    "email": "<string>",
    "firstname": "<string>",
    "lastname": "<string>"
  },
  "account": {
    "_id": "<string>",
    "name": "<string>",
    "country": "<string>",
    "sacId": 123,
    "oar_id": "<string>",
    "demoaccount": true,
    "socialCreditId": "<string>",
    "taxId": "<string>",
    "bluesignId": "<string>",
    "zdhcId": "<string>",
    "ipeViolation": {
      "totalViolations": 123
    },
    "ffcId": 123
  },
  "totalMaterialGlobalWarmingImpact": 123,
  "_rev": "<string>",
  "code": "<string>",
  "category": "<string>",
  "supplierCountry": "<string>",
  "nameId": "<string>",
  "supplier": "<string>",
  "country": "<string>",
  "tier2": {
    "isDefault": true,
    "assessment": {
      "_id": "<string>",
      "surveyVersion": "<string>",
      "country": "<string>",
      "processName": "<string>"
    },
    "facility": {
      "_id": "<string>",
      "name": "<string>",
      "country": "<string>",
      "sacId": 123,
      "oar_id": "<string>",
      "demoaccount": true,
      "socialCreditId": "<string>",
      "taxId": "<string>",
      "bluesignId": "<string>",
      "zdhcId": "<string>",
      "ipeViolation": {
        "totalViolations": 123
      },
      "ffcId": 123
    },
    "country": "<string>",
    "facilityRawText": "<string>"
  },
  "tier3": {
    "isDefault": true,
    "assessment": {
      "_id": "<string>",
      "surveyVersion": "<string>",
      "country": "<string>",
      "processName": "<string>"
    },
    "facility": {
      "_id": "<string>",
      "name": "<string>",
      "country": "<string>",
      "sacId": 123,
      "oar_id": "<string>",
      "demoaccount": true,
      "socialCreditId": "<string>",
      "taxId": "<string>",
      "bluesignId": "<string>",
      "zdhcId": "<string>",
      "ipeViolation": {
        "totalViolations": 123
      },
      "ffcId": 123
    },
    "country": "<string>",
    "facilityRawText": "<string>"
  },
  "baseMaterials": [
    {
      "_id": "<string>",
      "composition": 123,
      "name": "<string>",
      "baseMaterialProcesses": [
        {
          "_id": "<string>",
          "name": "<string>",
          "stageName": "<string>",
          "lifeCycle": "<string>",
          "isEligible": true,
          "totalMaterialGlobalWarmingImpact": 123,
          "totalLossRate": 123,
          "residualElectricityTotal": 123,
          "lossRate": 123,
          "assessment": {
            "_id": "<string>",
            "surveyVersion": "<string>",
            "country": "<string>",
            "processName": "<string>"
          },
          "facility": {
            "_id": "<string>",
            "name": "<string>",
            "country": "<string>",
            "sacId": 123,
            "oar_id": "<string>",
            "demoaccount": true,
            "socialCreditId": "<string>",
            "taxId": "<string>",
            "bluesignId": "<string>",
            "zdhcId": "<string>",
            "ipeViolation": {
              "totalViolations": 123
            },
            "ffcId": 123
          },
          "country": "<string>",
          "facilityType": [
            "<string>"
          ],
          "sipfacilitymaterialprocesstextiles": [
            "<string>"
          ],
          "materialproduction_normalized_kgco2e": 123,
          "rawmaterialprocessing_normalized_kgco2e": 123,
          "globalWarmingImpact": 123,
          "facilityRawText": "<string>"
        }
      ],
      "totalMaterialGlobalWarmingImpactT2": 123,
      "totalMaterialGlobalWarmingImpactT3": 123,
      "totalMaterialGlobalWarmingImpactT4": 123,
      "totalMaterialGlobalWarmingImpact": 123,
      "refKey": "<string>",
      "sustainability": {
        "isEligible": true,
        "processId": "<string>"
      },
      "manufacturer": "<string>",
      "tradeName": "<string>",
      "country": "<string>",
      "typeCode": "<string>",
      "materialSubtype": "<string>",
      "sustainabilityAttribute": "<string>",
      "baseMaterialProcessesList": [
        {
          "_id": "<string>",
          "name": "<string>",
          "stageName": "<string>",
          "lifeCycle": "<string>",
          "isEligible": true,
          "totalMaterialGlobalWarmingImpact": 123,
          "totalLossRate": 123,
          "residualElectricityTotal": 123,
          "lossRate": 123,
          "assessment": {
            "_id": "<string>",
            "surveyVersion": "<string>",
            "country": "<string>",
            "processName": "<string>"
          },
          "facility": {
            "_id": "<string>",
            "name": "<string>",
            "country": "<string>",
            "sacId": 123,
            "oar_id": "<string>",
            "demoaccount": true,
            "socialCreditId": "<string>",
            "taxId": "<string>",
            "bluesignId": "<string>",
            "zdhcId": "<string>",
            "ipeViolation": {
              "totalViolations": 123
            },
            "ffcId": 123
          },
          "country": "<string>",
          "facilityType": [
            "<string>"
          ],
          "sipfacilitymaterialprocesstextiles": [
            "<string>"
          ],
          "materialproduction_normalized_kgco2e": 123,
          "rawmaterialprocessing_normalized_kgco2e": 123,
          "globalWarmingImpact": 123,
          "facilityRawText": "<string>"
        }
      ],
      "uniqueCyclesAssessments": [
        {
          "assessmentId": "<string>",
          "processId": "<string>",
          "lifeCycle": "<string>",
          "isEligible": true,
          "sipfacilitymaterialprocesstextiles": "<string>"
        }
      ],
      "shortPath": {
        "yarnSize": "<string>",
        "autoFromShortPath": true
      },
      "v2Calculations": {
        "totalMaterialGlobalWarmingImpactT2": 123,
        "totalMaterialGlobalWarmingImpactT3": 123,
        "totalMaterialGlobalWarmingImpactT4": 123,
        "totalMaterialGlobalWarmingImpact": 123
      },
      "stages": [
        {
          "stageId": "<string>",
          "countryCode": "<string>",
          "source": "<string>",
          "disaggregated": true,
          "processId": "<string>",
          "lossRate": 123,
          "residualGWP": 123,
          "residualScope3GWP": 123,
          "totalElectricity": 123,
          "naturalGas": 123,
          "diesel": 123,
          "coal": 123,
          "systemBoundaryStages": [
            "<string>"
          ],
          "yarnSize": "<string>",
          "yarnUnit": "<string>",
          "countryGridEF": {
            "countryCode": "<string>",
            "gwp": 123,
            "eutrophication": 123,
            "waterScarcity": 123,
            "abioticDepletion": 123,
            "dataSource": "<string>"
          },
          "activityAttribute": "<string>",
          "country": "<string>",
          "dyeType": "<string>",
          "activityType": "<string>",
          "processType": "<string>",
          "manufacturer": "<string>",
          "textileFormation": "<string>",
          "enabledBy": "<string>",
          "intrinsicCharacteristic": "<string>",
          "layersCount": "<string>",
          "substratePURatio": "<string>",
          "programCertification": "<string>",
          "inputFor": "<string>",
          "contributor": "<string>",
          "upstreamProcessId": "<string>",
          "organizationId": "<string>",
          "approach": "<string>",
          "gwPerKg": 123,
          "outputMass": 123,
          "phaseGW": 123,
          "transport": 123
        }
      ]
    }
  ],
  "modifiedOn": 123,
  "deleted": true,
  "deletedBy": {
    "_id": "<string>",
    "email": "<string>",
    "firstname": "<string>",
    "lastname": "<string>"
  },
  "modifiedBy": {
    "_id": "<string>",
    "email": "<string>",
    "firstname": "<string>",
    "lastname": "<string>"
  },
  "createdBy": {
    "_id": "<string>",
    "email": "<string>",
    "firstname": "<string>",
    "lastname": "<string>"
  },
  "v2Calculations": {
    "totalMaterialGlobalWarmingImpactT2": 123,
    "totalMaterialGlobalWarmingImpactT3": 123,
    "totalMaterialGlobalWarmingImpactT4": 123,
    "totalMaterialGlobalWarmingImpact": 123
  },
  "msiVersion": "<string>",
  "tags": [
    "<string>"
  ]
}
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.

PIC | Create a Material with T2/T3 Links

​
Request body params

NameTypeDescription
namestring[REQUIRED] The name for your custom material.
cycleProcessArray<CycleProcess>[REQUIRED] Life cycle processes for this material (stages P002–P006).
cycleProcess[].lifeCyclestring[REQUIRED] The life cycle stage ID (e.g., "P002" for Yarn Formation, "P003" for Fabric Formation).
baseMaterialsArray<BaseMaterial>[REQUIRED] The base materials that compose this custom material.
baseMaterials[].idstring[REQUIRED] The base material ID. Use Get Base Materials to find IDs.
baseMaterials[].compositionnumber[REQUIRED] The percentage composition (all base materials must sum to 100%).
codestringOptional material code.
categorystringOptional material category.
supplierstringOptional supplier name.
supplierCountrystringOptional supplier country.
countrystringOptional country of origin.
cycleProcess[].countrystringCountry value for this process stage. Use Get Country List for valid values. Required if facilityWorldlyId is not provided.
cycleProcess[].facilityWorldlyIdstringWorldly facility ID for facility-specific data. Use Get Facilities to find available facilities.
baseMaterials[].sustainabilitystring | nullOptional 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.

Authorizations

​
x-api-key
string
header
required
​
x-developer-request-token
string
header
required

Body

application/json
​
name
string
required
​
cycleProcess
object[]
required
​
baseMaterials
object[]
required
​
code
string | null
​
category
string | null
​
supplierCountry
string | null
​
supplier
string | null
​
country
string | null

Response

200 - application/json

Ok

This interface was referenced by Exports's JSON-Schema via the definition "picMaterialLibraryEntity".

​
_id
string
required
​
type
string
required
​
name
string
required
​
t2GlobalWarmingImpact
number<double>
required
​
t3GlobalWarmingImpact
number<double>
required
​
t4GlobalWarmingImpact
number<double>
required
​
createdOn
number<double>
required
​
user
object
required

This interface was referenced by Exports's JSON-Schema via the definition "userRef".

​
account
object
required

This interface was referenced by Exports's JSON-Schema via the definition "accountRef".

​
totalMaterialGlobalWarmingImpact
number<double>
required
​
_rev
string | null
​
code
string | null
​
category
string | null
​
supplierCountry
string | null
​
nameId
string | null
​
supplier
string | null
​
country
string | null
​
tier2
object
​
tier3
object
​
baseMaterials
object[] | null
​
modifiedOn
number<double> | null
​
deleted
boolean | null
​
deletedBy
object

This interface was referenced by Exports's JSON-Schema via the definition "userRef".

​
modifiedBy
object

This interface was referenced by Exports's JSON-Schema via the definition "userRef".

​
createdBy
object

This interface was referenced by Exports's JSON-Schema via the definition "userRef".

​
v2Calculations
object

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.

​
msiVersion
string | null
​
tags
string[] | null