canonical: https://jentic.com/apis/getuku.com/getuku

# Getuku Uku API

The Uku API is the integration surface for the Uku practice-management platform used by accounting firms. Across 34 endpoints it covers clients, contacts, contracts, invoices, invoice sellers, and a login flow that issues JWT bearer tokens for subsequent calls. Accountants and accounting tools use it to sync client lists, push invoices into Uku, and read contract status without manual data entry across systems.

## For AI agents

Manage clients, contacts, contracts, and invoices in the Uku practice-management platform via 34 endpoints with JWT bearer authentication.

## Scope

Does not handle payment processing, payroll, or tax filing - use for Uku practice-management client, contract, and invoice records only.

## Capabilities

- Authenticate via POST /login and obtain a JWT bearer token for subsequent calls
- Create and list client records that drive billing and contract relationships
- Sync contact details against Uku for use in engagement letters
- Read invoice records and invoice-seller metadata for reconciliation
- Retrieve contract status to gate workflow steps in downstream tools
- Look up a single client, contact, contract, or invoice by id

## Use cases

### Sync Client Lists Between Uku and a CRM

Accounting firms running both a CRM and Uku must keep client lists aligned so engagement letters, invoices, and contracts route to the right party. The Uku API exposes client list and create endpoints so a sync job can mirror the CRM's customer table into Uku each night, with idempotent updates against the same Uku client id.

Example prompt: Pull the firm's CRM client list, then for each client call POST /clients in Uku if no matching record exists.

### Pull Invoice Status for Reconciliation

Accountants reconciling between Uku and a general ledger pull the Uku invoice list and per-invoice details to confirm which invoices are issued, paid, or outstanding. The /invoices and `/invoices/{invoice_id}` endpoints make this straightforward without exporting CSVs from the Uku UI.

Example prompt: List all invoices, then fetch full details for any whose status is 'pending' and report the totals.

### Contract Status Gating in Workflow Tools

When a workflow tool kicks off a tax or audit job, it can call the Uku contracts endpoint first to verify the client has a current signed engagement. The contract list and detail endpoints expose status so the workflow either proceeds or pauses the job until the engagement letter is in place.

Example prompt: Fetch contract id 998 and only proceed with downstream steps if status equals 'signed'.

### AI Agent Practice Management Tasks

An AI agent triaging accountant email can create Uku clients, look up contracts, and queue invoices without UI navigation. Through Jentic the agent finds each operation by intent ('create a client in Uku', 'list invoices for client'), loads the schema, and executes, while the JWT token stays in the encrypted vault.

Example prompt: Create a client named 'Acme Ltd' in Uku, then list any existing contracts for that client.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/login` | Authenticate and receive a JWT bearer token |
| GET | `/clients` | List clients |
| POST | `/clients` | Create a client record |
| GET | `/clients/{client_id}` | Retrieve a single client |
| GET | `/contracts` | List contracts |
| GET | `/invoices` | List invoices |
| GET | `/invoices/{invoice_id}` | Retrieve a single invoice |

## Key resources

- **Auth** — Login endpoint that returns a JWT bearer token
- **Clients** — List, create, and retrieve client records
- **Contacts** — Manage contact details linked to clients
- **Contracts** — List and retrieve contract records and status
- **Invoices** — Read invoice records and per-invoice details
- **Invoice Sellers** — List configured invoice-seller entities for the firm

## Why Jentic

- **Setup:** Wiring the Uku API by hand means logging in for a short-lived JWT, refreshing it against the app.getuku.com host before it expires, and re-attaching it on every call yourself. Through Jentic you install once, import the Uku API from the API Directory, store the login credential once, and your agent calls it.
- **Permission scoping:** Uku puts the client id in the URL path (`/clients/{client_id}`), so a rule can pin your agent to one client's record for reads. You choose the operations it may call, so creating clients or listing invoices across the practice is not included unless you add them.
- **Credential handling:** Your Uku login credential and the JWT it yields are stored once, encrypted, by your own Jentic One instance and injected at execution time, with refresh handled centrally. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a client in Uku' or 'list Uku invoices', and Jentic returns the matching Uku operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Xero Accounting** — Xero handles core accounting and ledger; Uku covers practice management for the accountant running it
- **Sage** — Sage is a client-facing accounting ledger; Uku is the firm-facing practice tool
- **Karbon** — Karbon is a comparable accounting practice management platform with its own API

## FAQ

### What authentication does the Uku API use?

Uku uses HTTP bearer authentication with a JWT token. POST /login exchanges the user's credentials for the JWT, which is then sent as Authorization: Bearer <token>. Through Jentic the credentials and resulting JWT are stored encrypted in the vault - the agent receives a scoped invocation capability rather than the raw token.

### Can I create a client with the Uku API?

Yes. POST /clients accepts the client payload and returns the created record with its id. Use GET /clients to verify the record exists before re-running a creation, since the spec does not declare an idempotency-key endpoint here.

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

The spec does not declare explicit rate limits. Production integrations should respect 429 responses, throttle bulk client and invoice sync jobs, and avoid running tight loops over /invoices for large client books.

### How do I retrieve invoices through Jentic?

Search Jentic for 'list uku invoices'. Jentic returns the GET /invoices operation with its query parameter schema; load it, optionally filter by client, and execute. For a single invoice's full payload, follow up with GET `/invoices/{invoice_id}.`

### Does the Uku API expose contract status?

Yes. GET /contracts lists contracts and GET `/contracts/{contract_id}` returns the full record including status. This is the standard gate to verify an engagement letter is signed before downstream automation runs.

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

Yes. Because you run Jentic One yourself, your own rules decide which Uku operations and credentials the agent may use. Since Uku puts the client id in the URL path, such as GET `/clients/{client_id}`, you can pin the agent to reading a single client's record. You also choose the operations it may call, so creating clients with POST /clients or listing invoices across the whole practice with GET /invoices stays off limits unless you grant them.