Chemical Products API — ConformaESG Integration Service

Endpoints

Method	Path	Description
`GET`	`/api/v1/chemicals`	List chemical products (paginated + filtered)
`GET`	`/api/v1/chemicals/{id}`	Get a chemical product by ID
`GET`	`/api/v1/chemicals/search`	Search by CAS number
`POST`	`/api/v1/chemicals`	Create a chemical product
`PATCH`	`/api/v1/chemicals/{id}`	Update a chemical product
`POST`	`/api/v1/chemicals/bulk`	Bulk upsert chemical products
`DELETE`	`/api/v1/chemicals/{id}`	Archive a chemical product (soft delete)

GET /api/v1/chemicals

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`0`	Zero-based page index
`size`	integer	`20`	Items per page
`category`	string	—	Filter by chemical category
`complianceStatus`	string	—	Filter by compliance status
`pfasContent`	boolean	—	Filter by PFAS content
`search`	string	—	Free-text search

Shell

curl "http://localhost:8080/api/v1/chemicals?category=DYES&search=blue&size=10"

GET /api/v1/chemicals/search

Search chemical products by CAS number. Supports exact and partial matching.

Parameter	Type	Default	Description
`casNumber`	string	—	CAS number to search for
`partial`	boolean	`false`	Enable partial matching
`page`	integer	`0`	Page index
`size`	integer	`20`	Page size

Shell
curl "http://localhost:8080/api/v1/chemicals/search?casNumber=2580-78-1"

curl "http://localhost:8080/api/v1/chemicals/search?casNumber=2580&partial=true"

POST /api/v1/chemicals

Request Body

Field	Type	Required	Description
`chemical_name`	string	✅	Chemical name
`commercial_name`	string	❌	Commercial/trade name
`internal_code`	string	❌	Internal product code
`cas_numbers`	array	❌	CAS Registry Numbers
`ec_number`	string	❌	EC number
`chemical_formula`	string	❌	Chemical formula
`chemical_category`	string	❌	Category
`subcategory`	string	❌	Subcategory
`user_id`	integer	❌	Creator user ID
`company_id`	integer	❌	Company ID
`metadata`	object	❌	Arbitrary JSON key-value pairs

The request also supports nested objects for compliance and supplier data:

Compliance Fields (nested under `compliance`)

Field	Type	Description
`reach_compliant`	boolean	REACH regulation compliant
`reach_registration_number`	string	REACH registration number
`zdhc_level`	string	`LEVEL_1`, `LEVEL_2`, `LEVEL_3`, `NOT_LISTED`
`zdhc_gateway_id`	string	ZDHC Gateway ID
`gots_compliant`	boolean	GOTS compliant
`grs_compliant`	boolean	GRS compliant
`svhc_substance`	boolean	Is SVHC substance
`pfas_content`	boolean	Contains PFAS

Supplier Fields (nested under `supplier`)

Field	Type	Description
`supplier_name`	string	Chemical supplier name
`supplier_code`	string	Supplier code
`contact_email`	string	Contact email
`country`	string	Supplier country

Shell
1curl -X POST http://localhost:8080/api/v1/chemicals \
-H "Content-Type: application/json" \
-d '{
  "chemical_name": "Reactive Blue 19",
  "commercial_name": "Remazol Brilliant Blue R",
  "cas_numbers": ["2580-78-1"],
  "chemical_category": "DYES",
  "user_id": 1,
  "company_id": 1,
  "compliance": {
    "reach_compliant": true,
    "zdhc_level": "LEVEL_2",
    "svhc_substance": false
  },
  "supplier": {
    "supplier_name": "ChemCo GmbH",
    "country": "DE"
  }
}'

JavaScript
1const resp = await fetch('/api/v1/chemicals', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
  chemical_name: 'Reactive Blue 19',
  cas_numbers: ['2580-78-1'],
  chemical_category: 'DYES',
  compliance: { reach_compliant: true, zdhc_level: 'LEVEL_2' },
  supplier: { supplier_name: 'ChemCo GmbH', country: 'DE' }
})
11});

DELETE /api/v1/chemicals/{id}

Archives a chemical product (soft delete — sets archived = true).

Shell

curl -X DELETE http://localhost:8080/api/v1/chemicals/42

Response: 204 No Content

POST /api/v1/chemicals/bulk

Bulk upserts chemical products.

JSON
1{
"items": [
  {
    "chemical_name": "Reactive Blue 19",
    "cas_numbers": ["2580-78-1"],
    "chemical_category": "DYES"
  },
  {
    "chemical_name": "Sodium Hydroxide",
    "cas_numbers": ["1310-73-2"],
    "chemical_category": "BASES"
  }
]
14}