canonical: https://jentic.com/apis/acmecompany.bizmerlin.net/bizmerlin-expense-reports # Acmecompany Bizmerlin Expense Reports Jentic publishes the only available OpenAPI specification for this BizMerlin HR (ClayHR) tenant API, keeping it validated and agent-ready. The API spans 143 endpoints across employee management areas including timesheets, timecards, expense reports, leaves, candidates, custom fields, goals, performance reviews, projects, surveys, announcements, and trainings. Authentication uses two API key headers: x-api-key and userid, scoping requests to a tenant user. The base URL is the customer's BizMerlin subdomain at acmecompany.bizmerlin.net. ## For AI agents Read and update HR records - timesheets, expense reports, leaves, performance reviews, goals, training, and recruiting - across a BizMerlin (ClayHR) tenant so agents can automate everyday HR operations. ## Scope Does not handle payroll runs, benefits enrollment, or single sign-on configuration - use for HR data operations (expenses, leaves, time, recruiting, performance, training, surveys) on the BizMerlin tenant only. ## Capabilities - Submit and approve expense reports across the employee lifecycle - Read and update timesheets and timecards for a given user - Manage leave requests, balances, and approvals - Track candidates through the recruiting pipeline including detail and list views - Run performance review cycles and read goal data per employee - Create and manage announcements, surveys, and training assignments - Read and write custom field values on people and project records ## Use cases ### Automated Expense Report Submission from Receipts An expense capture tool extracts receipt data externally and pushes the result into BizMerlin as an expense report via the expense endpoints. Reviewers approve in BizMerlin while employees never re-enter values. Token plus userid headers identify the submitting employee, and custom fields capture project allocation. This compresses end-of-month expense cycles. Example prompt: Create an expense report with three line items for a given employee userid, attach the receipt references, and submit for approval ### Manager Leave Approval Dashboard A manager-facing dashboard pulls pending leave requests via the leaves endpoints, presents them with employee context from the people endpoints, and writes the approval back. Managers approve from one screen instead of clicking into BizMerlin per request, and the system audit trail stays in the HR system of record. Example prompt: List all pending leave requests for the manager's reports, sort by submitted date, and approve the oldest five ### Recruiting Pipeline Sync to External ATS A recruiting tool keeps candidate stages in sync between an external ATS and BizMerlin by polling /list and `/detail/{recruitid}` on the candidates surface. Hiring managers see the same pipeline stage in BizMerlin that recruiters see in their ATS, and offer-letter triggers can flow back into BizMerlin onboarding. This avoids duplicate data entry across the two systems. Example prompt: List candidates updated in the last day and pull each candidate's full detail to compare with the ATS record ### Training Rollout via an HR Assistant Bot An HR assistant bot in Slack assigns mandatory trainings, posts announcements, and follows up on missing surveys. It calls the trainings, announcements, and survey endpoints through Jentic. Employees interact with the bot, the bot calls BizMerlin on their behalf, and the API key plus userid headers stay encrypted in the vault. Example prompt: Through Jentic, search 'assign a training to employees', load the trainings endpoint schema, and assign a security-awareness training to a list of userids ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/api/token` | Obtain a tenant API token | | GET | `/list` | List candidate records | | GET | `/detail/{recruitid}` | Retrieve candidate detail by id | | POST | `/api/announcement/create` | Create a company announcement | | GET | `/api/announcement/{annId}` | Retrieve an announcement | | PUT | `/api/announcement/edit` | Edit an existing announcement | | GET | `/customfield` | Read custom field values | ## Key resources - **Expense Reports** — Create, submit, and approve expense reports tied to employees and projects - **Timesheets and Timecards** — Read and update time entries per employee and pay period - **Leaves** — Manage leave requests, balances, and approvals - **Candidates** — Recruit pipeline records with list and detail endpoints - **Performance and Goals** — Performance review cycles and per-employee goals - **Trainings** — Assign and track training completion across employees - **Announcements and Surveys** — Tenant-wide communications and survey response tracking - **Custom Fields** — Read and write custom field values across people and project records ## Why Jentic - **Setup:** Wiring the BizMerlin Expense Reports API by hand means attaching both the x-api-key and userid headers on every call and navigating a large HR surface of expense, leave, recruiting, and survey endpoints yourself. Through Jentic you install once, import the Expense Reports API from the API Directory, store the x-api-key and userid once, and your agent calls it. - **Permission scoping:** This tenant surface spans many operations, so limit the agent to the operations it needs, such as submitting an expense report and reading its detail. You choose the operations it may call, so announcement editing or recruiting reads are not included unless you add them. - **Credential handling:** Your BizMerlin x-api-key and userid values are stored once, encrypted, by your own Jentic One instance and injected as headers at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'submit an expense report', and Jentic returns the matching BizMerlin operation with its schema and required header parameters so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **BambooHR API** — HR information system API for SMB people, time off, and reporting. - **Gusto API** — US-focused payroll, benefits, and HR API. - **Greenhouse API** — Dedicated ATS that complements BizMerlin's recruiting pipeline. ## FAQ ### Why is there no official OpenAPI spec for Expense Reports? BizMerlin (ClayHR) does not publish a public OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Expense Reports via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the BizMerlin (ClayHR) API use? Two API key headers - x-api-key for the tenant key and userid for the acting employee - on every request. Through Jentic, both values are stored encrypted in the vault and injected per call so the raw values stay out of agent context. ### Can I submit and approve expense reports through this API? Yes. The API exposes endpoints across the expense report lifecycle - creation, submission, and approval - keyed by the userid header. Pair these with the announcement and custom field endpoints to thread expense submission into broader HR workflows. ### What are the rate limits for the BizMerlin API? The OpenAPI spec does not document explicit rate limits. BizMerlin tenants typically share per-tenant capacity; treat large bulk operations as best-effort and back off on HTTP 429. For high-volume sync, batch reads through /list endpoints rather than re-querying detail per record. ### How do I assign a training to employees through Jentic? Run pip install jentic, then search 'assign a training to employees'. Jentic returns the relevant trainings endpoint with its input schema, you supply the training id and a list of userids, and execute. The x-api-key and userid headers are injected by Jentic at execution time. ### Does this API cover payroll and benefits? The endpoints in this spec focus on time, expenses, leaves, recruiting, performance, training, and announcements. Payroll and benefits are typically administered through BizMerlin's broader product surface and may not be present in this OpenAPI cut. Check the BizMerlin developer documentation for those modules. ### Can I limit what my agent is allowed to do with the BizMerlin HR API? Yes. Because you run Jentic One yourself, your own rules decide which of this tenant's operations the agent may call and which credentials it may use. This HR surface spans many operations, so you can scope the agent to just the ones it needs, such as submitting an expense report and reading its detail, while leaving out announcement editing or recruiting reads unless you add them. Your x-api-key and userid values are held by your own instance and injected at execution time, so the agent only touches the operations you allow.