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/apiInteractive docs (Swagger): /api/docs/
Requests must include the JWT header:
Authorization: Bearer <access_token>Login (obtain token)
Body: {"email": "user@example.com", "password": "***"}
Response: {"access": "<JWT>", "refresh": "<refresh_token>"}. Use access in the header Authorization: Bearer <access>.
Body: {"refresh": "<refresh_token>"}. Returns a new access when the token has expired.
/api/user/ (see Swagger). For integration, token and refresh are sufficient.File upload
PDF file upload and confirmation to start processing. All endpoints under /api/files/.
List uploaded documents (status uploaded) for the authenticated user.
Body: multipart/form-data — fields pdf (file), title (optional), eer_codes (optional, comma-separated).
Response: created document data (e.g. id, filename).
Confirm uploaded files and start processing (async task). Requires an active subscription.
Response: task_id, message: "Processing started!".
Delete an uploaded document.
Add one or more EER codes to the document. Body: {"eer_codes": "code1,code2"}.
Remove an EER code from the document.
Add one EER code to all documents currently in upload. Body: {"eer_code": "..."}.
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/.
List parsed records. Query: eer_codes (filter). Additional filters via filterset (see Swagger).
Single parsed record details.
Update record data (e.g. product name, composition, item fields). Body: fields to update (partial). See Swagger for schemas.
Add an EER code to the document linked to the parsed record.
Remove an EER code from the record's document.
Check if selected records can be validated (e.g. EER already in HP Finder). Body: filters as in list.
Move records from Parsed to Validated (HP Finder). Body: filters to select records. Requires EER assigned.
Assign records to a customer and send to History. Body: customer (customer id), filters, remove_from_parsed (true to move to history and remove from parsed).
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. Optional body: language (e.g. en).
Export validated filtered data to Excel. Query: eer_codes (required), language (optional, default en). Response: Excel file as attachment.
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. Paginated response.
History
Document history (company-wide: all company users).
List documents in history. Filters via filterset (see Swagger for fields).
Export filtered history to Excel. Query: language (optional). Response: Excel file as attachment.
Delete a record from history.
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: filters (see Swagger). 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.
Body (e.g.): {"email": "...", "name": "...", "role": "..."}. Create or invite user.
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.