Materials

List materials

get

Returns active materials in the tenant, paginated. Each entry carries the material's display name, its description, and unit (from the material's measurement unit).

Query

search — optional case-insensitive substring match on the material's name.
page / limit — defaults page = 1, limit = 25, max limit = 100.

Authorizations

x-api-keystringRequired

Query parameters

searchstring · max: 100Optional

Case-insensitive substring match on name.

pagenumber · min: 1OptionalDefault: 1

limitnumber · min: 1 · max: 100OptionalDefault: 25

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

429

Returned when the rate limit is exceeded

get/api/v1/public/materials

GET /api/v1/public/materials HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "unit": "text"
    }
  ],
  "meta": {
    "total": 1,
    "lastPage": 1,
    "currentPage": 1,
    "perPage": 1,
    "prev": 1,
    "next": 1
  }
}

Create material

post

The API gives the ability to create a new material and specify material properties.

Scenarios for processing the received data

📝 All required + optional parameters were passed

The system creates material in the system.

UI

Newly created material is added to the Materials page to the {Category} tab and {Subcategory} section, which were passed in the “CREATE a material” request.
- If category_name wasn't specified in the request, then material is added to the “Without category” tab on the Materials page.
- If subcategory_name wasn't specified in the request, then material is added to the {Category} tab which was passed in the “CREATE a material” request, but added to the “Without subcategory” section on the Materials page.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestringRequired

Name of the material

Example: Premium Steel Rod

measurement_unit_idstring · uuidRequired

UUID of the measurement unit for this material

Example: 550e8400-e29b-41d4-a716-446655440000

material_external_idstringOptional

External identifier for the material from supplier or other system

Example: MAT-2024-001

descriptionstringOptional

Detailed description of the material

Example: High-grade steel rod with corrosion resistance, suitable for construction

material_category_idstring · uuidOptional

UUID of the material category

Example: 550e8400-e29b-41d4-a716-446655440001

material_subcategory_idstring · uuidOptional

UUID of the material subcategory

Example: 550e8400-e29b-41d4-a716-446655440002

material_supplier_idstring · uuidOptional

UUID of the material supplier

Example: 550e8400-e29b-41d4-a716-446655440003

purchase_pricenumber · min: 1Optional

Purchase price of the material in base currency

Example: 25.99

actual_pricenumber · min: 1Optional

Current actual price of the material in base currency

Example: 28.5

statusstring · enumOptional

Status of the material (Default status if no value provided: ACTIVE)

Example: ACTIVEPossible values:

materialCharacteristicsstring · uuid[] · max: 10Optional

Array of material characteristic UUIDs (max 10)

Example: ["550e8400-e29b-41d4-a716-446655440004","550e8400-e29b-41d4-a716-446655440005"]

tagsstring · uuid[]Optional

Array of tag UUIDs for categorization and filtering

Example: ["550e8400-e29b-41d4-a716-446655440006","550e8400-e29b-41d4-a716-446655440007"]

Responses

201Success

application/json

idstring · uuidRequired

Unique identifier of the material

Example: 550e8400-e29b-41d4-a716-446655440000

material_category_idstring · nullableRequired

ID of the material category

Example: 550e8400-e29b-41d4-a716-446655440001

material_subcategory_idstring · nullableRequired

ID of the material subcategory

Example: 550e8400-e29b-41d4-a716-446655440002

material_supplier_idstring · nullableRequired

ID of the material supplier

Example: 550e8400-e29b-41d4-a716-446655440003

image_idstring · nullableRequired

ID of the associated image

Example: 550e8400-e29b-41d4-a716-446655440004

material_external_idstring · nullableRequired

External identifier for the material

Example: MAT-001

measurement_unit_idstring · uuidRequired

ID of the measurement unit

Example: 550e8400-e29b-41d4-a716-446655440005

namestringRequired

Name of the material

Example: Steel Beam

descriptionstring · nullableRequired

Description of the material

Example: High-strength steel beam for construction

statusstring · enumRequired

Current status of the material

Example: ACTIVEPossible values:

purchase_pricenumber · nullableRequired

Purchase price of the material

Example: 150

actual_pricenumber · nullableRequired

Actual price of the material

Example: 175.75

supply_delivery_timenumber · nullableRequired

Supply delivery time value

Example: 5

supply_delivery_time_periodstring · nullableRequired

Supply delivery time period unit

Example: days

created_atstring · date-timeRequired

Date when the material was created

Example: 2023-01-01T00:00:00.000Z

updated_atstring · date-time · nullableRequired

Date when the material was last updated

Example: 2023-01-02T00:00:00.000Z

created_bystring · nullableRequired

ID of the user who created the material

Example: 550e8400-e29b-41d4-a716-446655440006

updated_bystring · nullableRequired

ID of the user who last updated the material

Example: 550e8400-e29b-41d4-a716-446655440007

429

Returned when the rate limit is exceeded

post/api/v1/public/materials

POST /api/v1/public/materials HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 699

{
  "name": "Premium Steel Rod",
  "measurement_unit_id": "550e8400-e29b-41d4-a716-446655440000",
  "material_external_id": "MAT-2024-001",
  "description": "High-grade steel rod with corrosion resistance, suitable for construction",
  "material_category_id": "550e8400-e29b-41d4-a716-446655440001",
  "material_subcategory_id": "550e8400-e29b-41d4-a716-446655440002",
  "material_supplier_id": "550e8400-e29b-41d4-a716-446655440003",
  "delivery_time": {
    "value": 3,
    "unit": "h"
  },
  "purchase_price": 25.99,
  "actual_price": 28.5,
  "status": "ACTIVE",
  "materialCharacteristics": [
    "550e8400-e29b-41d4-a716-446655440004",
    "550e8400-e29b-41d4-a716-446655440005"
  ],
  "tags": [
    "550e8400-e29b-41d4-a716-446655440006",
    "550e8400-e29b-41d4-a716-446655440007"
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "material_category_id": "550e8400-e29b-41d4-a716-446655440001",
  "material_subcategory_id": "550e8400-e29b-41d4-a716-446655440002",
  "material_supplier_id": "550e8400-e29b-41d4-a716-446655440003",
  "image_id": "550e8400-e29b-41d4-a716-446655440004",
  "material_external_id": "MAT-001",
  "measurement_unit_id": "550e8400-e29b-41d4-a716-446655440005",
  "name": "Steel Beam",
  "description": "High-strength steel beam for construction",
  "status": "ACTIVE",
  "purchase_price": 150,
  "actual_price": 175.75,
  "supply_delivery_time": 5,
  "supply_delivery_time_period": "days",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-02T00:00:00.000Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440006",
  "updated_by": "550e8400-e29b-41d4-a716-446655440007"
}

Get material measurement units

get

The API gives the ability to get all material measurement units.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

idstring · uuidRequired

Unique identifier of the measurement unit

Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

namestringRequired

Measurement unit name

Example: kg

429

Returned when the rate limit is exceeded

get/api/v1/public/materials/measurement_units

GET /api/v1/public/materials/measurement_units HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

[
  {
    "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
    "name": "kg"
  }
]

Add photo to material

post

The API gives the ability to add photo to material.

Scenarios for processing the received data

📝 Photo was passed successfully

System sets this photo as a main photo for a material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

urlstringRequired

Photo url

Example: https://example.com/photos/material-photo.jpg

Responses

201Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

post/api/v1/public/materials/{material_id}/photos

POST /api/v1/public/materials/{material_id}/photos HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "url": "https://example.com/photos/material-photo.jpg"
}

{
  "message": "The operation was done successfully"
}

Update material

patch

The API gives the ability to update materials properties. Any parameters not provided will be left unchanged.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestringOptional

Name of the material

Example: Premium Steel Rod

measurement_unit_idstring · uuidOptional

UUID of the measurement unit for this material

Example: 550e8400-e29b-41d4-a716-446655440000

material_external_idstringOptional

External identifier for the material from supplier or other system

Example: MAT-2024-001

descriptionstringOptional

Detailed description of the material

Example: High-grade steel rod with corrosion resistance, suitable for construction

material_category_idstring · uuidOptional

UUID of the material category

Example: 550e8400-e29b-41d4-a716-446655440001

material_subcategory_idstring · uuidOptional

UUID of the material subcategory

Example: 550e8400-e29b-41d4-a716-446655440002

material_supplier_idstring · uuidOptional

UUID of the material supplier

Example: 550e8400-e29b-41d4-a716-446655440003

purchase_pricenumber · min: 1Optional

Purchase price of the material in base currency

Example: 25.99

actual_pricenumber · min: 1Optional

Current actual price of the material in base currency

Example: 28.5

statusstring · enumOptional

Status of the material

Example: ACTIVEPossible values:

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

patch/api/v1/public/materials/{material_id}

PATCH /api/v1/public/materials/{material_id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 506

{
  "name": "Premium Steel Rod",
  "measurement_unit_id": "550e8400-e29b-41d4-a716-446655440000",
  "material_external_id": "MAT-2024-001",
  "description": "High-grade steel rod with corrosion resistance, suitable for construction",
  "material_category_id": "550e8400-e29b-41d4-a716-446655440001",
  "material_subcategory_id": "550e8400-e29b-41d4-a716-446655440002",
  "material_supplier_id": "550e8400-e29b-41d4-a716-446655440003",
  "delivery_time": {
    "value": 3,
    "unit": "h"
  },
  "purchase_price": 25.99,
  "actual_price": 28.5,
  "status": "ACTIVE"
}

{
  "message": "The operation was done successfully"
}

Add parameters to a material

post

The API gives the ability to add parameter to material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

Responses

201Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

post/api/v1/public/materials/{material_id}/parameters

POST /api/v1/public/materials/{material_id}/parameters HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "data": [
    {
      "parameter_id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "parameter_value_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

{
  "message": "The operation was done successfully"
}

Remove material parameter from material

delete

The API gives the ability to remove parameter from material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

parameter_idstring · UUIDRequired

Parameter ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

delete/api/v1/public/materials/{material_id}/parameters/{parameter_id}

DELETE /api/v1/public/materials/{material_id}/parameters/{parameter_id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}

Update material parameter value for material

patch

The API gives the ability to update material parameter value.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

parameter_idstring · UUIDRequired

Parameter ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

parameter_value_idstring · uuidRequired

Unique identifier of the parameter value to update

Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

patch/api/v1/public/materials/{material_id}/parameters/{parameter_id}

PATCH /api/v1/public/materials/{material_id}/parameters/{parameter_id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "parameter_value_id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e"
}

{
  "message": "The operation was done successfully"
}

Remove all material parameters from material

delete

The API gives the ability to remove all parameters from material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

delete/api/v1/public/materials/{material_id}/parameters-all

DELETE /api/v1/public/materials/{material_id}/parameters-all HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}

Add tag to a material

post

The API gives the ability to add tag to material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

tag_idsstring · uuid[]Required

Array of tag UUIDs for categorization and filtering

Example: ["550e8400-e29b-41d4-a716-446655440006","550e8400-e29b-41d4-a716-446655440007"]

Responses

201Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

post/api/v1/public/materials/{material_id}/tags

POST /api/v1/public/materials/{material_id}/tags HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "tag_ids": [
    "550e8400-e29b-41d4-a716-446655440006",
    "550e8400-e29b-41d4-a716-446655440007"
  ]
}

{
  "message": "The operation was done successfully"
}

Remove tag from a material

delete

The API gives the ability to remove tag from material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

tag_idstringRequired

Tag ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

delete/api/v1/public/materials/{material_id}/tags/{tag_id}

DELETE /api/v1/public/materials/{material_id}/tags/{tag_id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}

Remove all tags from a material

delete

The API gives the ability to remove all tags from material.

Authorizations

x-api-keystringRequired

Path parameters

material_idstringRequired

Material ID

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully

429

Returned when the rate limit is exceeded

delete/api/v1/public/materials/{material_id}/tags-all

DELETE /api/v1/public/materials/{material_id}/tags-all HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}

PreviousMaterial Tags

NextOrders

Last updated 13 days ago