# COUNT Partner API

> Official documentation for the COUNT Partner API — the REST API for building accounting integrations on COUNT.

The COUNT Partner API lets your product read and write a customer's accounting data — customers, invoices, bills, bank transactions, journal entries, and reports — once that customer authorizes your app.

Every request carries two layers of auth: an HMAC `x-signature` header computed with your partner clientSecret, proving the request came from your app, and a workspace-scoped OAuth bearer token scoping it to one customer's books. Read "Authentication & Signing" before anything else.

All routes are relative to the partner base URL and begin with `/partners`. List endpoints share a common response envelope and are paginated with `page` and `limit`.

## When to use this API

Use COUNT when the task involves a business's own books:

- Reading or creating customers, invoices, estimates and credit memos
- Reading or creating vendors and bills, and recording payment against them
- Importing, categorising, reviewing or reconciling bank transactions
- Posting journal entries and reading the chart of accounts
- Producing financial reports — profit and loss, balance sheet, trial balance, aged receivables and payables, sales by customer or product
- Budgets, projects, tasks, time entries and payroll

Do not use COUNT for general financial or tax advice, for filing returns, or for moving money to third parties. It records and reports on a business's own books.

Which surface to use:

- **An agent in a chat client** — the remote MCP server at `https://api.getcount.com/mcp`. Typed tools, OAuth consent, no request signing to implement. Start here unless you are writing server-side code.
- **Server-side code** — the REST Partner API at `https://api.getcount.com`. Full control; every request carries an HMAC signature plus a workspace bearer token.
- **Local development** — the COUNT CLI, which serves the same tools to a local agent over stdio.

Retries: every POST accepts an `Idempotency-Key` header — send the same key to replay the original response rather than create a second record. Rate limits are 100 requests per minute per clientId, reported on every response in `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, with `Retry-After` on a 429.

Before writing to a workspace: call `COUNT_auth_status` first, because one connection can authorize several workspaces and those are separate legal entities. Read the ledger semantics guide before any write — it lists, per operation, the state it is valid in and the calls that cannot be undone (merging customers, completing a reconciliation, publishing a budget, sending an invoice).

- [Agent instructions](https://developers.getcount.com/agents.md): The full version of this section — surface selection, irreversible operations, and the rules for bulk writes.
- [Authentication guide](https://developers.getcount.com/AUTH.md): Machine-readable auth: the HMAC base string, the token exchange, and the error table.

## Getting Started
- [Build on COUNT](https://developers.getcount.com/index.md): Read and write a customer's accounting data — invoices, transactions, customers — once they authorize your app. Every request is signed and workspace-scoped.
- [Authentication & Signing](https://developers.getcount.com/getting-started/authentication.md): Two layers of auth: an HMAC signature proving the request came from your app, and a workspace access token scoping it to one customer's data.
- [API Access Credentials](https://developers.getcount.com/getting-started/credentials.md): How partner clientId and clientSecret credentials work, how to request them, and how to register redirect URIs. The secret signs requests and is never sent.
- [Response Shapes & Data Models](https://developers.getcount.com/getting-started/response-shapes.md): Every Partner API response shares a common envelope, with list payloads nested under a resource-specific key. Know the shape before you parse it.
- [Quickstart](https://developers.getcount.com/getting-started/quickstart.md): Go from credentials to your first signed COUNT Partner API call: register a redirect URI, complete the OAuth exchange, then read workspace data.
- [OAuth Consent Experience](https://developers.getcount.com/getting-started/oauth-consent.md): What your users see when they connect COUNT to your app, and what you need to implement on the redirect back to your product.
- [Errors & Troubleshooting](https://developers.getcount.com/getting-started/errors.md): Diagnose COUNT Partner API failures fast — signing mistakes, token problems, validation errors, and rate limits, with the response each one returns.

## Tutorials
- [Integrate with COUNT](https://developers.getcount.com/tutorials/integrate.md): Watch the whole partner integration run: register an app, take a user through OAuth consent, exchange the code for a workspace token, then sign your first request.
- [Connect an Agent over MCP](https://developers.getcount.com/tutorials/mcp.md): Watch an MCP client connect to COUNT — add the remote server, scope it to a workspace on the consent screen, then ask questions instead of calling endpoints.
- [Set Up the COUNT CLI](https://developers.getcount.com/tutorials/cli.md): Watch the COUNT CLI set up end to end: install, store partner credentials, log in through the browser, then serve the same tools to an agent over stdio.
- [Send a Request with Try it](https://developers.getcount.com/tutorials/try-it.md): Watch a signed Partner API request go out from the browser — credentials, a connected workspace, an endpoint from the reference, and the raw 200 that comes back.

## Guides
- [Accounting Playbooks](https://developers.getcount.com/guides/playbooks.md): Ordered, multi-step COUNT workflows — billing a customer, paying a vendor bill, migrating historical books, closing a month — with the exact tool to call at each step.
- [Ledger Semantics & Lifecycles](https://developers.getcount.com/guides/ledger-semantics.md): What each Partner API write actually does to the books: the state every operation is valid in, the fields accepted then ignored, and the calls that cannot be undone.
- [Create a Customer, Invoice, and Send It](https://developers.getcount.com/guides/create-customer-invoice-send.md): A complete billing flow on the COUNT Partner API: create the customer, build an invoice with line items, approve it, and send it.
- [Sync Bank Transactions](https://developers.getcount.com/guides/sync-transactions.md): Import bank transactions into COUNT from your own app, categorize them, and optionally link them to bills or invoices.
- [Handle Pagination](https://developers.getcount.com/guides/handle-pagination.md): Walk every page of a COUNT list endpoint using the page and limit query parameters and the totalPages field in the response.
- [Idempotency & Retries](https://developers.getcount.com/guides/idempotency-and-retries.md): Retry a failed COUNT Partner API write without creating it twice: the Idempotency-Key header, what a replay looks like, the two different 409s, and how to back off on a 429.
- [Verify Webhook Deliveries](https://developers.getcount.com/guides/verify-webhooks.md): Verify that a webhook delivery genuinely came from COUNT and was not tampered with, using the signing secret on your webhook subscription.
- [Refresh an Access Token](https://developers.getcount.com/guides/refresh-access-token.md): Exchange a refresh token for a new workspace access token so your integration keeps working without sending the user through consent again.
- [MCP Brain & Workspace Memory](https://developers.getcount.com/guides/mcp-brain-and-memory.md): How the COUNT MCP connector ranks knowledge, playbook, and tool lookups from plain-language questions, keeps workspace memory, and takes problem reports from agents.

## API Reference
- [API Reference index](https://developers.getcount.com/reference.md): Every documented endpoint, grouped by resource.
- [Customers API](https://developers.getcount.com/reference/customers.md): Customers are the people and businesses you invoice. A customer carries its contact details, billing and shipping addresses, contacts, and tax settings. Routes: GET /partners/customers, GET /partners/customers/{uuid}, POST /partners/customers, PUT /partners/customers/{uuid}, POST /partners/customers/bulk, PATCH /partners/customers/bulk, DELETE /partners/customers/{uuid}, GET /partners/customers/{uuid}/contacts, POST /partners/customers/{uuid}/contacts, PUT /partners/customers/{uuid}/contacts/{contactUuid}, DELETE /partners/customers/{uuid}/contacts/{contactUuid}, GET /partners/customers/{uuid}/addresses, POST /partners/customers/{uuid}/addresses, PUT /partners/customers/{uuid}/addresses/{customerAddressUuid}, DELETE /partners/customers/{uuid}/addresses/{customerAddressUuid}, GET /partners/customers/{uuid}/notes, POST /partners/customers/{uuid}/notes, PUT /partners/customers/{uuid}/notes/{noteUuid}, DELETE /partners/customers/{uuid}/notes/{noteUuid}, GET /partners/customers/{uuid}/revenue-overview, POST /partners/customers/merge/preview, POST /partners/customers/merge
- [Invoices API](https://developers.getcount.com/reference/invoices.md): Invoices, estimates, and credit memos share the same routes, distinguished by invoiceType. Every invoice object includes a derived status field (draft, approved, sent, unpaid, partial, paid, overdue, void) alongside the raw isDraft / approved / isSent / paymentStatus flags. All references use UUIDs. Routes: GET /partners/invoices, GET /partners/invoices/{uuid}, GET /partners/invoices/generate/number, POST /partners/invoices, PATCH /partners/invoices/{uuid}, PATCH /partners/invoices/{uuid}/approve, POST /partners/invoices/{uuid}/send, GET /partners/invoices/{uuid}/public-link, GET /partners/invoices/{uuid}/audit-log, GET /partners/invoices/{uuid}/send-history, POST /partners/invoices/{uuid}/attachments, POST /partners/invoices/{uuid}/attachments/upload, PATCH /partners/invoices/{uuid}/apply-multiple-credit-to-invoice, PATCH /partners/invoices/{uuid}/apply-credit-to-multiple-invoices, PATCH /partners/invoices/{uuid}/remove-credit, PATCH /partners/invoices/{uuid}/add-transactions, PATCH /partners/invoices/{uuid}/remove-transaction, DELETE /partners/invoices/{uuid}
- [Credit Memos API](https://developers.getcount.com/reference/credit-memo.md): Credit memos reduce what a customer owes. They are invoice records with invoiceType memo and use the same /partners/invoices routes as invoices and estimates. Apply approved memos to open invoices with the credit-application endpoints. Routes: GET /partners/invoices, GET /partners/invoices/{uuid}, POST /partners/invoices, PATCH /partners/invoices/{uuid}, PATCH /partners/invoices/{uuid}/approve, DELETE /partners/invoices/{uuid}, PATCH /partners/invoices/{uuid}/apply-multiple-credit-to-invoice, PATCH /partners/invoices/{uuid}/apply-credit-to-multiple-invoices, PATCH /partners/invoices/{uuid}/remove-credit
- [Recurring Invoice Templates API](https://developers.getcount.com/reference/recurring-invoice-templates.md): Recurring invoice templates define a schedule that automatically generates invoices (or estimates) in a workspace. Each template stores the invoice payload, recurrence cadence, and next run date. Credit memos cannot be recurring. Routes: GET /partners/recurring-invoice-templates, POST /partners/recurring-invoice-templates, GET /partners/recurring-invoice-templates/{uuid}, PATCH /partners/recurring-invoice-templates/{uuid}, DELETE /partners/recurring-invoice-templates/{uuid}, POST /partners/recurring-invoice-templates/{uuid}/pause, POST /partners/recurring-invoice-templates/{uuid}/resume
- [Bills API](https://developers.getcount.com/reference/bills.md): Bills are vendor payables — amounts your workspace owes to suppliers. Partner routes cover listing, creating, updating, approving, and deleting bills, applying vendor memos, and removing transaction payments. All references use UUIDs. Routes: GET /partners/bills, GET /partners/bills/{uuid}, POST /partners/bills, PATCH /partners/bills/{uuid}, DELETE /partners/bills/{uuid}, POST /partners/bills/{uuid}/submit, POST /partners/bills/{uuid}/approve, POST /partners/bills/{uuid}/apply-vendor-memos, POST /partners/bills/{uuid}/assign-transaction, POST /partners/bills/{uuid}/unassign-transaction
- [Transactions API](https://developers.getcount.com/reference/transactions.md): Transactions are the individual money movements on a workspace account. Amounts are signed: negative for money out (expense) and positive for money in (income). All references (account, category, vendor, customer, tags) use UUIDs. Routes: GET /partners/transactions, GET /partners/transactions/{uuid}, POST /partners/transactions, POST /partners/transactions/bulk, PATCH /partners/transactions/{uuid}, PATCH /partners/transactions/{uuid}/change-category, PATCH /partners/transactions/change-category-bulk, POST /partners/transactions/review-bulk, PATCH /partners/transactions/exclude-bulk, POST /partners/transactions/{uuid}/assign-to-bills-invoices, PUT /partners/transactions/{uuid}/split, DELETE /partners/transactions/{uuid}
- [Chart of Accounts API](https://developers.getcount.com/reference/chart-of-accounts.md): The chart of accounts is the workspace general ledger. Every transaction, bill, invoice line, and journal entry line posts to an account. Accounts are organized by high-level type (Assets, Liabilities, Equity, Income, Expenses) and a numeric sub-type. Routes: GET /partners/chart-of-accounts, GET /partners/account-sub-types, POST /partners/chart-of-accounts, PATCH /partners/chart-of-accounts/{uuid}, DELETE /partners/chart-of-accounts/{uuid}, POST /partners/chart-of-accounts/bulk
- [Vendors API](https://developers.getcount.com/reference/vendors.md): Vendors are the suppliers, merchants, contractors, and contacts you pay through bills and expense transactions. A vendor holds contact details, an optional address, 1099 tax settings, and status. Routes: GET /partners/vendors, POST /partners/vendors, PATCH /partners/vendors/{uuid}, DELETE /partners/vendors/{uuid}
- [Products & Services API](https://developers.getcount.com/reference/products-and-services.md): Products and services are the catalog items you sell on invoices and estimates. Each record carries pricing, optional inventory tracking, income and purchase category accounts, and tax configuration. Routes: GET /partners/products, POST /partners/products, GET /partners/products/{uuid}, PATCH /partners/products/{uuid}, DELETE /partners/products/{uuid}
- [Journal Entries API](https://developers.getcount.com/reference/journal-entries.md): Journal entries are manual double-entry postings to the general ledger. Each posting has a memo, date, optional reference number, and balanced debit/credit lines that reference chart-of-accounts UUIDs. Routes: GET /partners/journal-entries, POST /partners/journal-entries, POST /partners/journal-entries/bulk, PATCH /partners/journal-entries/{uuid}, DELETE /partners/journal-entries/{uuid}
- [Budgets API](https://developers.getcount.com/reference/budgets.md): Budgets let partners create workspace financial plans with versioned cell grids. Partner responses expose budget UUIDs as `id`, strip internal numeric foreign keys, and require `accountUuid` (not numeric `accountId`) on cell update payloads. Routes: GET /partners/budgets/overall, GET /partners/budgets, POST /partners/budgets, GET /partners/budgets/{uuid}, PATCH /partners/budgets/{uuid}, DELETE /partners/budgets/{uuid}, GET /partners/budgets/{uuid}/grid, GET /partners/budgets/{uuid}/versions, POST /partners/budgets/{uuid}/versions, PATCH /partners/budgets/{uuid}/versions/{versionNumber}/cells, POST /partners/budgets/{uuid}/versions/{versionNumber}/cells/bulk, POST /partners/budgets/{uuid}/publish, POST /partners/budgets/{uuid}/archive, POST /partners/budgets/{uuid}/duplicate
- [Tags API](https://developers.getcount.com/reference/tags.md): Tags are workspace labels used to classify transactions, journal entries, invoices, bills, and other records. Tag groups organize related tags — each tag may belong to at most one group. Routes: GET /partners/tags, GET /partners/tags/{uuid}, POST /partners/tags, PATCH /partners/tags/{uuid}, DELETE /partners/tags/{uuid}, GET /partners/tags/groups, GET /partners/tags/groups/{uuid}, POST /partners/tags/groups, PATCH /partners/tags/groups/{uuid}, DELETE /partners/tags/groups/{uuid}
- [Webhooks API](https://developers.getcount.com/reference/webhooks.md): Subscribe to workspace events and receive HTTPS POST deliveries when matching records change. Each subscription covers one event type per workspace. Routes: GET /partners/webhooks, POST /partners/webhooks, PATCH /partners/webhooks/{uuid}, DELETE /partners/webhooks/{uuid}
- [Documents API](https://developers.getcount.com/reference/documents.md): Upload, list, update, and delete files in a workspace document library. Large files use a chunked upload flow. Partner responses omit internal storage paths and download URLs. Routes: GET /partners/documents, GET /partners/documents/{uuid}, POST /partners/documents, PUT /partners/documents/{uuid}, GET /partners/document-types, PUT /partners/documents/{uuid}/document-type, PUT /partners/documents/{uuid}/period, DELETE /partners/documents/{uuid}, POST /partners/documents/chunk-upload/initiate, POST /partners/documents/chunk-upload/chunk, POST /partners/documents/chunk-upload/complete, GET /partners/documents/chunk-upload/progress/{uploadProgressId}
- [People API](https://developers.getcount.com/reference/people.md): People are workspace members — employees, contractors, and other payroll or expense-reporting contacts. Partner responses expose UUIDs as `id` and omit internal numeric foreign keys. Routes: GET /partners/people, GET /partners/people/{uuid}
- [Projects API](https://developers.getcount.com/reference/projects.md): Projects group work for a customer with a status, schedule, and associated tasks. Partner responses use UUIDs; numeric `customerId` and `statusId` fields are stripped. Routes: GET /partners/projects/statuses, GET /partners/projects, POST /partners/projects, POST /partners/projects/bulk, GET /partners/projects/{uuid}/tasks, GET /partners/projects/{uuid}, PATCH /partners/projects/{uuid}, DELETE /partners/projects/{uuid}
- [Tasks API](https://developers.getcount.com/reference/tasks.md): Tasks are units of work with assignees, statuses, deadlines, and optional project links. Partner responses expose UUIDs; numeric foreign keys on the task root are stripped. Routes: GET /partners/tasks, GET /partners/tasks/{uuid}, POST /partners/tasks, PATCH /partners/tasks/{uuid}, DELETE /partners/tasks/{uuid}
- [Time Entries API](https://developers.getcount.com/reference/time-entries.md): Time entries record minutes logged by a person against projects, customers, and billable services. Partner responses use UUIDs; entries in processed pay periods are read-only. Routes: GET /partners/time-entries, GET /partners/time-entries/{uuid}, POST /partners/time-entries, PATCH /partners/time-entries/{uuid}, DELETE /partners/time-entries/{uuid}
- [Expense Receipts API](https://developers.getcount.com/reference/expense-receipts.md): Expense receipts (pending receipts) capture out-of-pocket expenses before they are matched to bank transactions. Upload receipt images via multipart form data; API responses omit receiptUrl by design. Routes: GET /partners/expense-receipts, GET /partners/expense-receipts/unmatched, POST /partners/expense-receipts, PATCH /partners/expense-receipts/{uuid}, DELETE /partners/expense-receipts/{uuid}, POST /partners/expense-receipts/{uuid}/match-manually, DELETE /partners/expense-receipts/{uuid}/unmatch
- [Connections API](https://developers.getcount.com/reference/connections.md): List and manage bank-feed connections (Plaid, Akahu, and similar). New connections require a human to complete Plaid Hosted Link in a browser. Routes: GET /partners/connections, POST /partners/connections/connect-link, POST /partners/connections/connect-link/complete, GET /partners/connections/{uuid}, PATCH /partners/connections/{uuid}/revoke, POST /partners/connections/{uuid}/reconnect-link
- [Reconciliations API](https://developers.getcount.com/reference/reconciliations.md): Start a bank reconciliation draft for an account statement period, correct or delete it while it is a draft, then complete it to mark reviewed journal entries as reconciled. Routes: POST /partners/reconciliations, PATCH /partners/reconciliations/{uuid}, DELETE /partners/reconciliations/{uuid}, PATCH /partners/reconciliations/{uuid}/complete
- [Opening Balance API](https://developers.getcount.com/reference/opening-balance.md): Read and publish the workspace opening (conversion) balance as of the cutover date. Total debits must equal total credits. Routes: GET /partners/opening-balance, POST /partners/opening-balance
- [Workspace API](https://developers.getcount.com/reference/workspace.md): Read and update workspace-level settings for the authenticated workspace: the bookkeeping cutover date and the workspace’s GST configuration. Routes: PATCH /partners/workspace, GET /partners/workspace/gst-settings, PATCH /partners/workspace/gst-settings
- [Reports API](https://developers.getcount.com/reference/reports.md): Generate trial balance, profit and loss, balance sheet, AR/AP aging, sales analytics, customer activity, and account transactions (general-ledger detail) reports for a workspace. All routes use POST with filters on the query string — there is no request body. Routes: POST /partners/reports/trial-balance, POST /partners/reports/pnl, POST /partners/reports/balance-sheet, POST /partners/reports/aged-receivables, POST /partners/reports/aged-payables, POST /partners/reports/sales-by-product-service, POST /partners/reports/sales-by-customer, POST /partners/reports/customer-report, POST /partners/reports/account-transactions
- [Workspace Stats API](https://developers.getcount.com/reference/workspace-stats.md): Aggregated CFO-style business snapshot for a workspace — cash, profitability, receivables, payables, tax obligations, and bank connections in one GET call. Routes: GET /partners/workspace-stats

## Tools
- [SDKs & Templates](https://developers.getcount.com/sdks.md): Starter projects with HMAC signing and OAuth token handling already wired up — add your credentials, pick the endpoints you want, and run.
- [COUNT CLI](https://developers.getcount.com/tools/count-cli.md): The COUNT CLI bundles OAuth login and a local MCP server so Claude Code, Cursor, and other agent runtimes can read and write workspace data.
- [MCP Server](https://developers.getcount.com/tools/mcp.md): Run the COUNT Partner MCP server locally through the CLI for Claude Code and Cursor, or connect the remote server to Claude.ai and ChatGPT.
- [Claude Plugin](https://developers.getcount.com/tools/claude-plugin.md): Install the COUNT plugin for Claude: the COUNT connector plus a /count skill that routes each request to a playbook, FAQ topic, saved workspace skill, or tool, and updates without a reinstall.
- [Prompt Library](https://developers.getcount.com/tools/prompt-library.md): Ready-made prompts for building a COUNT Partner API integration — OAuth, HMAC, and REST snippets — plus prompts for MCP workspace automation.
- [Prompt Generator](https://developers.getcount.com/tools/prompt-generator.md): Generate a detailed prompt for your AI coding assistant covering OAuth, HMAC signing, bank connections, and the REST endpoints you actually need.
- [Try it](https://developers.getcount.com/tools/try-it.md): Send a signed COUNT Partner API request from your browser and inspect the raw response. Credentials stay in this tab's sessionStorage.
- [Signature Generator](https://developers.getcount.com/tools/signature-generator.md): Compute a valid x-signature for any COUNT Partner API request in your browser — the fastest way to check your own signing implementation.

## AI Toolkit
- [AI Toolkit](https://developers.getcount.com/ai.md): Ship a COUNT Partner API integration with an AI coding assistant, or automate workspace tasks from an agent using the MCP server and COUNT CLI.

## Resources
- [FAQ](https://developers.getcount.com/resources/faq.md): Quick answers to the questions partners ask most often when integrating with COUNT, each linked to the full documentation.
- [Partner Program](https://developers.getcount.com/resources/partner-program.md): How COUNT onboards partners — from your first OAuth app to a live integration, what we review, and how support works after you go live.
- [About](https://developers.getcount.com/about.md): Who publishes the COUNT Partner API documentation, what the API covers, and how to verify COUNT — trust centre, status page, and source.
- [Contact](https://developers.getcount.com/contact.md): How to reach COUNT about the Partner API, a partnership application, a security report, or an outage, and what to include so support can find your request.
- [Privacy](https://developers.getcount.com/privacy.md): What this documentation site does with the credentials you enter into Try it, what it stores locally, and where COUNT’s binding privacy policy lives.
- [Security & Webhook Operations](https://developers.getcount.com/resources/security-and-operations.md): COUNT Partner API authentication, data handling, rate limits, and outbound webhook delivery — written for security reviewers and integration engineers.
- [Versioning & Deprecation Policy](https://developers.getcount.com/resources/versioning-and-deprecation.md): How COUNT classifies breaking vs. non-breaking Partner API changes, the notice given before one ships, and how to track compatibility.
- [Changelog](https://developers.getcount.com/changelog.md): Every COUNT Partner API change — new endpoints, MCP tools, fields, and behavior changes — listed with the resource groups each one affects.

## Optional
- [Full documentation text](https://developers.getcount.com/llms-full.txt): Every page on this site inlined as markdown in one file — fetch this instead of crawling the links above.
- [OpenAPI 3.0 specification](https://developers.getcount.com/openapi.json): Every documented endpoint as a machine-readable spec, generated from this same reference.
- [Postman collection](https://developers.getcount.com/postman-collection.json): Importable collection with a pre-request script that computes the HMAC signature headers.
- [Changelog feed](https://developers.getcount.com/changelog.json): Machine-readable changelog — poll it for entries where `breaking` is true against the groups you call. Breaking changes carry at least 90 days notice.
- [Sitemap](https://developers.getcount.com/sitemap.xml): Every indexable documentation URL.