Client API integration
After purchasing a subscription, users can: upload documents in Upload, view and edit parsed documents (Parsed file), assign EER codes, export tables (parsed, history, validated), send data to History by assigning it to a customer, use Validate/HP Finder and HP Finder functions. This documentation lists the endpoints needed to integrate your software with HSE Genius.
Base URL and authentication
API base URL:
https://kaimakicloud.hsegenius.com/apiRequests must include the JWT header:
Authorization: Bearer <access_token>Login (obtain token)
Body (required schema):
{
"email": str,
"password": str
}Response: {"access": "<JWT>", "refresh": "<refresh_token>"}. Use access in the header Authorization: Bearer <access>.
Returns a new access when the token has expired.
Body (required schema):
{
"refresh": str
}File upload
PDF file upload and confirmation to start processing. All endpoints under /api/files/.
List uploaded documents (status created) for the authenticated user.
Body: multipart/form-data. Schema:
{
"pdf": file, // optional
"eer_codes": [str] // optional
}Response: created document data (e.g. id, filename).
Confirm uploaded files and start processing (async task). Requires an active subscription.
Body: none.
Response: task_id, message: "Processing started!".
Delete an uploaded document.
Add one or more EER codes to the document.
Body (required schema):
{
"eer_codes": [str]
}Remove an EER code from the document.
Add one EER code to all documents currently in upload.
Body (required schema):
{
"eer_code": str
}Parsed file (parsed data)
Documents after processing (status confirmed): list, search, edit, assign EER, send to History with customer, validate to HP Finder. Endpoints under /api/files/imported/.
validate-constraint, validate, history, hp-finder/proceed and hp-finder/export POST endpoints. All fields are optional.{
"nome_file": str|null,
"nome_del_prodotto": str|null,
"cod_art": str|null,
"produttore": str|null,
"zdhc": str|null,
"data_di_revisione": str|null,
"uso_appropriato": str|null,
"stato_fisico": str|null,
"h_punto_2": [int],
"precautionary_statements": [str],
"user_document_item_details": [{
"composizione_punto_3": str|null,
"cas": str|null,
"ce_no": str|null,
"reach": str|null,
"h_punto_3": [int],
"concentrazione": str|null,
"svch": obj|null,
"allegato_xiv": obj|null
}],
"ghs": [int],
"pericoloso_per_lambiente": bool|null,
"numero_onu": str|null,
"gruppo_di_imballaggio": str|null,
"classe": str|null,
"punto_di_ebollizione": str,
"ph": str,
"cov": str,
"notes": str|null,
"seveso_code_h2": str,
"seveso_code_p15": str,
"sds_8_2_technical_controls": str|null,
"sds_8_2_ppe_hands": str|null,
"sds_8_2_ppe_skin": str|null,
"sds_8_2_ppe_body": str|null,
"sds_8_2_ppe_eyes": str|null,
"sds_8_2_ppe_respiratory": str|null,
"sds_8_2_hygiene_other": str|null,
"sds_8_2_ppe_environmental_exposure": str|null,
"sds_8_2_ppe_complementary_emergency_measures": str|null,
"sds_8_2_ppe_thermal_risk": str|null
}List parsed records. Query: eer_codes (filter).
Single parsed record details.
Update record data (e.g. product name, composition, item fields). Body: fields to update, partial (see Record schema above).
Add an EER code to the document linked to the parsed record.
Body: none (parameters in the path).
Remove an EER code from the record's document.
Check if selected records can be validated (e.g. EER already in HP Finder).
Body (schema): record fields, all optional (see Record schema above).
Move records from Parsed to Validated (HP Finder). Requires EER assigned.
Body (schema):
{
"id": [int], // optional, ids of the records to validate
...record fields // optional, see "Record schema"
}Assign records to a customer and send to History.
Body (schema):
{
"id": [int], // optional, record ids
"customer": int|null, // customer id
"remove_from_parsed": bool, // true to move to history and remove from parsed
...record fields // optional, see "Record schema"
}Export parsed file table to Excel (with filters). Query: language (optional).
Validated / HP Finder
Validated data (after validate from Parsed): list, export table, mark as processed and move to History.
List validated records. Query: eer_codes (EER filter).
Mark records as processed and move to history. Required query: eer_codes.
Body (schema):
{
"id": [int], // optional, record ids
"language": enum("it", "en"), // optional
"customer": int|null, // optional, customer id
...record fields // optional, see "Record schema"
}Export validated filtered data to Excel. Query: eer_codes (required), language (optional, default en). Response: Excel file as attachment.
Body (schema):
{
"id": [int], // optional, record ids
"language": enum("it", "en"), // optional
"customer": int|null, // optional, customer id
...record fields // optional, see "Record schema"
}HP Finder (H/P codes)
List of Hazard/Process codes used for search and HP Finder functions.
List of all HP ordered by h_punto.
History
Document history (company-wide: all company users).
List documents in history.
Export filtered history to Excel. Query: language (optional). Response: Excel file as attachment.
Delete a record from history. This endpoint is only available for admin.
Export
Excel export from parsed data, validated data and history.
Export parsed data (status confirmed) to Excel. Query: language (optional). Response: Excel attachment.
Export history to Excel. Query: language. Response: Excel attachment.
Export validated data to Excel. Query: eer_codes, language. Body: see the schema in the Validated / HP Finder section. Response: Excel attachment.
EER codes
List of available EER codes (for upload, filters and validation). Under /api/eer/.
List EER codes. Useful for dropdowns when assigning EER to documents or filtering parsed/validated.
Customers
Company customers: for assigning documents sent to History. Under /api/customer/.
List company customers. Use the id in the body of POST /api/files/imported/history/ (field customer).
Users
Company user management (company admin only). Under /api/company/.
List users in the authenticated user's company.
Create or invite user.
Body (required schema):
{
"email": str,
"first_name": str,
"last_name": str,
"phone": str,
"country_code": str,
"role": enum("admin", "employee", "viewer", "auditor")
}Single user details.
Update user (e.g. role).
Remove user from company.
Subscription
Active company subscription details.
Returns the company's active subscription (plan, limits, status). 404 if no active subscription.
Analytics (admin only)
Analytical dashboard on the company's SDS inventory. Accessible only to company admins (CompanyAdminPermission). All endpoints under /api/files/.
403 Forbidden for users with role employee or viewer.Returns aggregated metrics for the SDS inventory. Optional query: user_id (filter by a specific company user).
Response (JSON object):
kpi— total, validated, in_progress, svch, this_month, trendghs— top GHS pictograms with document counthp— top HP hazard classes (section 2) with countdpi— % SDS per required PPE type (sec. 8.2)clienti— SDS distribution by customer/siteheatmap— monthly uploads over the last 12 monthsalerts— regulatory alerts (svch, allegato_xiv, env_hazard)extra_alerts— special alerts: cmr, alert_conc, seveso, old_sdseer— hazardous vs non-hazardous waste countproduttori— top manufacturers by SDS countusers— company user list with document count (for filter bar)
Exports the same dashboard metrics as a downloadable file.
Query:
format—csv(default) orxlsxuser_id— optional, filter by user
Response: .csv or .xlsx attachment with separate sheets for KPI, GHS, HP, DPI, Customers, Uploads, Compliance, EER, Manufacturers.