canonical: https://jentic.com/apis/karbonhq.com/karbon

# Karbonhq Karbon API

Jentic publishes the only available OpenAPI specification for Karbon API, keeping it validated and agent-ready. Karbon is practice management software for accounting firms, and its API exposes contacts, organisations, work items, notes, timesheets, tasks, tags, and users so firms can sync client data, automate engagement workflows, and roll up time and capacity reporting. The v3 endpoints follow REST conventions and use bearer-token authentication issued from the Karbon admin console.

## For AI agents

Manage contacts, organisations, work items, tasks, notes, and timesheets inside an accounting firm's Karbon practice. 45 endpoints covering the full client engagement workflow.

## Scope

Does not handle general-ledger postings, payroll, or tax filing - use for accounting firm practice management (clients, work items, tasks, notes, timesheets) only.

## Capabilities

- Create and update contact records linked to organisations via /contacts and `/contacts/{id}`
- Manage client organisations including their tags and client groups via /organizations and /clientGroups
- Drive engagements with work items and tasks via /workItems and /tasks endpoints
- Capture client communication and meeting notes through /notes endpoints
- Pull billable and non-billable time entries via /timesheets
- Resolve users and team members for assignment and capacity views via /users

## Use cases

### Client Data Sync from CRM to Karbon

Mirror client and contact data from an accounting firm's CRM into Karbon so the practice management system always has up-to-date contact details, organisation links, and tags. The /contacts and /organizations endpoints accept create and patch payloads with rich relationship fields, so a one-way sync runs cleanly on a nightly schedule. Removes a recurring source of stale-data errors when accountants pull client records during tax season.

Example prompt: List recent CRM updates and upsert each as a Karbon contact via POST /contacts or PATCH `/contacts/{id}`, linking to the parent organisation.

### Engagement Automation for Tax Season

Auto-create a Karbon work item with its task list every time a new tax-return engagement is signed in the firm's onboarding system. The API creates the work item under the correct client organisation, attaches default tasks, and assigns them to the right accountant based on the firm's load balancing rules. Saves administrators 5-10 minutes per engagement during peak load.

Example prompt: Create a 'Tax Return 2026' work item via POST /workItems for client organisation {id} and add five tasks via POST /tasks assigned to the lead accountant.

### Capacity and Utilisation Reporting

Pull timesheet entries from Karbon nightly into a data warehouse so partners can run capacity and utilisation reports outside Karbon's built-in views. The /timesheets endpoint exposes entries with user, work item, billable flag, and duration so a small ETL can compute realisation, utilisation by team, and time-by-client without a third-party BI add-on.

Example prompt: Pull timesheet entries via GET /timesheets for the last 7 days and aggregate hours by user and client organisation.

### Agent-Driven Practice Management

An accounting firm's internal AI assistant uses Jentic to update Karbon directly when a partner asks 'mark John's tax return as complete' or 'add a meeting note for Acme Co'. Jentic resolves the right work item or organisation by name and executes the call, with the bearer token held server-side so the assistant never sees the raw secret.

Example prompt: Use the Jentic search 'add a note to a Karbon client', load the schema, and POST /notes with the client organisation ID and meeting summary.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/contacts` | List client contacts |
| POST | `/contacts` | Create a new contact |
| GET | `/organizations/{id}` | Retrieve a client organisation |
| POST | `/workItems` | Create a work item for an engagement |
| POST | `/tasks` | Create a task on a work item |
| POST | `/notes` | Add a note to a client record |
| GET | `/timesheets` | List time entries for the firm |

## Key resources

- **Contacts** — Create, list, update, and resolve client contacts.
- **Organizations** — Manage client organisations, including their tags and client group membership.
- **Work Items** — Drive engagements with structured work items per client.
- **Tasks** — Manage tasks attached to work items, with assignees and due dates.
- **Notes** — Capture client communication, meeting summaries, and internal notes.
- **Timesheets** — List and create time entries with billable flags and durations.
- **Users** — Resolve team members for assignment and reporting.

## Why Jentic

- **Setup:** Wiring the Karbon API by hand means learning its bearer auth, calling api.karbonhq.com/v3, and mapping contacts, work items, tasks, and notes to their request shapes yourself. Through Jentic you install once, import the Karbon API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Most Karbon writes post to collection endpoints like /workItems, /tasks, and /notes rather than a resource id in the path, so scope the agent by the operations it needs, such as creating a work item or reading timesheets. You pick that set, so an agent built to file notes is not given contact creation unless you add it.
- **Credential handling:** Your Karbon bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Karbon work item' or 'list open tasks', and Jentic returns the matching Karbon operation with its request schema so the agent calls the right endpoint without reading Karbon's docs.

## Related APIs

- **Xero Accounting API** — General ledger that pairs with Karbon's practice management for accountants.
- **HubSpot CRM** — Sales CRM whose contacts and organisations sync into Karbon as clients.
- **Asana API** — Generic task management - used in place of Karbon by smaller firms without practice-management features.
- **Clockify API** — Standalone time tracking alternative to Karbon's timesheet module.

## FAQ

### Why is there no official OpenAPI spec for Karbon API?

Karbon does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Karbon API 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 Karbon API use?

The API uses HTTP bearer tokens. Each request must include `Authorization: Bearer {token}` where the token is generated from the Karbon admin console. Through Jentic, tokens are encrypted in the vault and scoped per execution so the raw bearer never enters the agent's context.

### Can I create a work item for a client engagement via the Karbon API?

Yes. POST /workItems creates a work item bound to a client organisation, and POST /tasks adds tasks under that work item. This is the standard flow for spinning up a tax-return or audit engagement programmatically at the start of the season.

### What are the rate limits for the Karbon API?

Karbon enforces per-tenant throttling and returns HTTP 429 when bursts exceed the limit. The published guidance for v3 is to keep below ~10 requests per second per tenant - check the firm's Karbon plan if a heavier sync is needed and use server-side filtering on /timesheets to keep payloads small.

### How do I add a meeting note to a client through Jentic?

Run `pip install jentic` and search Jentic for 'add a note to a Karbon client'. Jentic returns the schema for POST /notes; supply the organisation or contact ID and the note body, then execute to attach the note.

### Can I list all open tasks assigned to a specific accountant?

Yes. GET /tasks supports filtering by assignee user ID and status, so you can return all incomplete tasks owned by a single accountant. Combine with GET /users to resolve names to IDs first.

### Is the Karbon API included in every plan?

API access is available on Karbon's paid plans but not on the trial tier. Higher-volume integrations (full timesheet exports, large-firm syncs) may require a custom rate-limit arrangement with Karbon support.

### Can I limit what my agent is allowed to do with the Karbon API?

Yes. Because Jentic One is self-hosted, you decide which Karbon operations and credentials your agent may use, and it can only call the endpoints you allow. Most Karbon writes post to collection endpoints such as /workItems, /tasks, and /notes, so you scope the agent by operation, for example letting it create notes without also granting contact creation on /contacts. An agent set up to file notes cannot create work items or read /timesheets unless you add those operations to its allowed set.