COUNT

Getting Started

**COUNT** — _Modern accounting software for ambitious businesses_ — empowers companies to manage their finances with confidence, efficiency, and transparency. As businesses grow, they often rely on a suite of specialized tools to handle everything from payroll and invoicing to inventory and customer relationship management. Recognizing this need, COUNT now enables seamless integration with third-party software and services.

With this new capability, external applications can securely access and interact with a user’s COUNT account — strictly within the boundaries of user-granted permissions. This means connected services can automate accounting-related tasks such as posting transactions, retrieving chart of accounts, accessing vendor data, and fetching invoice information — all while reducing manual effort and improving operational efficiency.

This integration model is built around secure, standards-based authentication and authorization protocols. By acting on behalf of users, approved third-party applications can extend COUNT’s core functionality while keeping users in full control of their data and access.

This documentation is designed for developers who want to build such integrations. It covers the entire process — from registering an integration and obtaining credentials to handling authorization flows and securely interacting with COUNT APIs.

Before You Get Started
----------------------

To successfully integrate with COUNT and follow along with this guide, make sure you have the following in place:

*   **COUNT Partner Account** – You’ll need to register as a COUNT partner to gain access to developer tools and integration management.
    
*   **Client ID and Client Secret** – These credentials are used to identify and authenticate your integration with COUNT’s API.
    
*   **Redirect URI** – This is a callback endpoint that COUNT will redirect to after a user authorizes your application. It plays a critical role in the OAuth flow, where it receives an authorization code that your server can exchange for an access token. This token allows your integration to perform actions on behalf of the user. We’ll show you how to implement this endpoint in the next steps.
    

⚠️ If you don’t have a partner account or access credentials yet, please fill the form below or press 👉 [here](https://docs.google.com/forms/d/e/1FAIpQLSe7AxXMSObX94XmEpF-Oxdbmsd6Gm0k9-0iccjVvA4s04pkMg/viewform) to request access and get started.

<Video url="https://docs.google.com/forms/d/e/1FAIpQLSe7AxXMSObX94XmEpF-Oxdbmsd6Gm0k9-0iccjVvA4s04pkMg/viewform"/>

Once these pieces are in place, you're ready to begin building a secure and user-consented integration with COUNT.

### API Base URLs

All COUNT Partner API requests must be sent to one of the following base URLs.

**BaseUrl(Development phase):** [**https://dev-api.getcount.com**](https://dev-api.getcount.com)

#### Note \* : Production Base URL will be provided once integration is complete.

All endpoint paths in this documentation are relative to the base URL.

Example Full URL: [https://dev-api.getcount.com/partners/customers](https://dev-api.getcount.com/partners/customers)

Introduction

⚠️ Important: All Requests Must Be Signed
-----------------------------------------

To ensure request authenticity and integrity, **all requests sent from your backend to COUNT's API must be signed** using your client secret. This signature helps prevent tampering, replay attacks, and unauthorized access.

**All API requests** (except Initiate Authorization and token exchange) require **two layers of authentication**:

1.  **Partner Authentication (HMAC)** — Every request must include an HMAC-SHA256 signature in the headers to verify your application's identity.
    
2.  **User Authentication (Bearer Token)** — Data endpoints (chart of accounts, vendors, bills, etc.) also require a Bearer access token to identify which user and workspace you're acting on behalf of.
    

**Rate Limiting:** API requests are rate-limited to **100 requests per minute** per client ID. Exceeding this will result in a `429` error.

**Redirect URI:** Your registered redirect URI **must not** contain query parameters. Use the `state` parameter to pass custom context through the OAuth flow — it is returned to you untouched with the authorization code.

**IDs:** All IDs returned by the API are UUIDs. When referencing resources (workspaces, customers, accounts, etc.), always use the UUID format.

We **strongly recommend** using a reusable Axios instance with request signing built in, as shown below.

### 🔐 Signature Requirements

Each request must include three critical headers:

*   `x-client-id` should contain your unique client identifier, which you’ll find in your COUNT dashboard.
    
*   `x-timestamp` must be the current UNIX timestamp in seconds when the request is made.
    
*   `x-signature` is the computed HMAC SHA-256 signature based on the request details and your client secret.
    

The signature is generated using a combination of the HTTP method, the request path (excluding domain), the timestamp, and the hashed request body (for `POST`, `PUT`, or `PATCH` methods). These are combined into a single string, hashed using your client secret, and attached to the request.

📋 Signature Canonicalization Rules
-----------------------------------

### Path Component

**Only the URL pathname is used in the signature - query parameters are excluded.**

*   ✅ **Include**: The pathname portion of the URL (e.g., `/customers`, `/customers/123`, `/invoices`)
    
*   ❌ **Exclude**: Query string parameters (e.g., `?page=1&limit=10&search=test`)
    
*   ❌ **Exclude**: Domain/hostname (e.g., `https://api.getcount.com`)
    
*   ❌ **Exclude**: Protocol (e.g., `https://`)
    

**Examples:**

*   URL: `https://api.getcount.com/customers?page=1&limit=10`
    
*   Path used in signature: `/customers` (query string ignored)
    
*   URL: `https://api.getcount.com/customers/abc-123?include=balance`
    
*   Path used in signature: `/customers/abc-123` (query string ignored)
    

### Request Body Hashing

**For POST, PUT, and PATCH requests only:**

1.  The request body must be a JSON object
    
2.  The body is hashed using SHA-256 after JSON stringification
    
3.  **Important**: JSON is stringified as-is with no canonicalization (key ordering, whitespace, etc. are preserved as you send them)
    
4.  Empty bodies or non-JSON bodies result in an empty string hash
    

**Body Hash Rules:**

*   ✅ **Include body hash for**: `POST`, `PUT`, `PATCH` methods
    
*   ❌ **Exclude body hash for**: `GET`, `DELETE`, `HEAD`, `OPTIONS` methods (empty string used)
    
*   ✅ **Hash format**: SHA-256 of `JSON.stringify(body)`
    
*   ⚠️ **Note**: The exact JSON stringification matters - ensure consistent serialization
    

### HMAC Base String Format

The base string follows this exact format:

Where:

*   `METHOD` is the uppercase HTTP method (e.g., `GET`, `POST`, `PUT`, `PATCH`, `DELETE`)
    
*   `/path` is the URL pathname only (no query string, no domain)
    
*   `timestamp` is the UNIX timestamp in seconds (as a string)
    
*   `bodyHash` is the SHA-256 hash of the JSON body (empty string for GET/DELETE/etc.)
    

**Examples:**

1.  **GET request:**
    
    1.  Method: `GET`
        
    2.  Path: `/customers`
        
    3.  Timestamp: `1704067200`
        
    4.  Body Hash: \`\` (empty for GET)
        
    5.  Base String: `GET:/customers:1704067200:`
        
2.  **GET with query parameters:**
    
    1.  Method: `GET`
        
    2.  Path: `/customers` (query string `?page=1&limit=10` is ignored)
        
    3.  Timestamp: `1704067200`
        
    4.  Body Hash: \`\` (empty for GET)
        
    5.  Base String: `GET:/customers:1704067200:`
        
3.  **POST request:**
    
    1.  Method: `POST`
        
    2.  Path: `/customers`
        
    3.  Timestamp: `1704067200`
        
    4.  Body: `{"name": "Test Customer", "email": "test@example.com"}`
        
    5.  Body Hash: `a1b2c3d4e5f6...` (SHA-256 of JSON string)
        
    6.  Base String: `POST:/customers:1704067200:a1b2c3d4e5f6...`
        

⚠️ Important Notes
------------------

1.  **Query Parameters**: Query string parameters (e.g., `?page=1&limit=10`) are **NOT** included in the signature. Only the pathname is used.
    
2.  **JSON Body Serialization**: The exact JSON stringification matters. Use consistent serialization - the same object must produce the same JSON string every time. Consider:
    
    1.  Key ordering (if your JSON library preserves it)
        
    2.  Whitespace (if your JSON library includes it)
        
    3.  Number formatting
        
    4.  Date serialization
        
3.  **Timestamp Accuracy**: Ensure your server time is accurate. Requests with timestamps that are too old or too far in the future will be rejected.
    

Below is the recommended setup using a reusable Axios client to handle signing automatically.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"javascript","label":"JavaScript"}'>
  <CodeLine>const axios = require("axios");
const crypto = require("crypto");// Create an Axios instance with base URL and static x-client-id header
const countClient = axios.create({
  baseURL: process.env.COUNT_PARTNER_API_ENDPOINT,
  headers: {
    "x-client-id": process.env.COUNT_CLIENT_ID,
  },
});// Attach the interceptor with a reusable signing function
countClient.interceptors.request.use(signRequest, (error) => Promise.reject(error));// Function that handles signing the request
function signRequest(config) {
  const method = (config.method || "GET").toUpperCase();
  const url = config.url || "/";
  const urlPath = new URL(url, config.baseURL).pathname;
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const clientSecret = process.env.COUNT_CLIENT_SECRET;
  const body = config.data || {};  const signature = generateSignature({
    method,
    path: urlPath,
    timestamp,
    body,
    clientSecret,
  });  config.headers["x-timestamp"] = timestamp;
  config.headers["x-signature"] = signature;  return config;
}// Hash the request body using SHA-256
function hashBody(body) {
  return body && Object.keys(body).length > 0
    ? crypto.createHash("sha256").update(JSON.stringify(body)).digest("hex")
    : "";
}// Build the HMAC base string in the format: METHOD:/path:timestamp:bodyHash
function buildHmacBaseString(method, path, timestamp, bodyHash = "") {
  return ${method}:${path}:${timestamp}:${bodyHash};
}// Generate the HMAC-SHA256 signature
function generateSignature({ method, path, timestamp, body, clientSecret }) {
  const bodyHash = ["POST", "PUT", "PATCH"].includes(method)
    ? hashBody(body)
    : "";  const baseString = buildHmacBaseString(method, path, timestamp, bodyHash);  return crypto
    .createHmac("sha256", clientSecret)
    .update(baseString)
    .digest("hex");
}</CodeLine>
  <CodeLine>const axios = require("axios");
const crypto = require("crypto");</CodeLine>
  <CodeLine>// Create an Axios instance with base URL and static x-client-id header
const countClient = axios.create({
  baseURL: process.env.COUNT_PARTNER_API_ENDPOINT,
  headers: {
    "x-client-id": process.env.COUNT_CLIENT_ID,
  },
});</CodeLine>
  <CodeLine>// Attach the interceptor with a reusable signing function
countClient.interceptors.request.use(signRequest, (error) => Promise.reject(error));</CodeLine>
  <CodeLine>// Function that handles signing the request
function signRequest(config) {
  const method = (config.method || "GET").toUpperCase();
  const url = config.url || "/";
  const urlPath = new URL(url, config.baseURL).pathname;
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const clientSecret = process.env.COUNT_CLIENT_SECRET;
  const body = config.data || {};</CodeLine>
  <CodeLine>  const signature = generateSignature({
    method,
    path: urlPath,
    timestamp,
    body,
    clientSecret,
  });</CodeLine>
  <CodeLine>  config.headers["x-timestamp"] = timestamp;
  config.headers["x-signature"] = signature;</CodeLine>
  <CodeLine>  return config;
}</CodeLine>
  <CodeLine>// Hash the request body using SHA-256
function hashBody(body) {
  return body && Object.keys(body).length > 0
    ? crypto.createHash("sha256").update(JSON.stringify(body)).digest("hex")
    : "";
}</CodeLine>
  <CodeLine>// Build the HMAC base string in the format: METHOD:/path:timestamp:bodyHash
function buildHmacBaseString(method, path, timestamp, bodyHash = "") {
  return ${method}:${path}:${timestamp}:${bodyHash};
}</CodeLine>
  <CodeLine>// Generate the HMAC-SHA256 signature
function generateSignature({ method, path, timestamp, body, clientSecret }) {
  const bodyHash = ["POST", "PUT", "PATCH"].includes(method)
    ? hashBody(body)
    : "";</CodeLine>
  <CodeLine>  const baseString = buildHmacBaseString(method, path, timestamp, bodyHash);</CodeLine>
  <CodeLine>  return crypto
    .createHmac("sha256", clientSecret)
    .update(baseString)
    .digest("hex");
}</CodeLine>
</CodeBlock>

Ensure your server time is accurate and your `clientSecret` is never exposed on the client side. Requests with invalid or expired signatures will be rejected by COUNT’s API.

Important Note

#### Requesting API Access Credentials

To obtain your **Client ID** and **Client Secret**, you must submit a formal access request through the COUNT API Access Request Form.

### How to Request Access

1.  Visit the [COUNT API Access Request Form](https://docs.google.com/forms/d/e/1FAIpQLSe7AxXMSObX94XmEpF-Oxdbmsd6Gm0k9-0iccjVvA4s04pkMg/viewform)
    
2.  Fill in the required details:
    

### What Happens After You Submit

Once your request is reviewed and approved by the COUNT team, you will receive:

*   **Client ID** — A unique identifier for your application, used in the `x-client-id` header for API requests.
    
*   **Client Secret** — A private key used to sign all API requests via HMAC-SHA256. This must be kept secure and never exposed on the client side.
    
*   **Redirect URI Configuration** — Your specified callback URL will be registered for the OAuth authorization flow.
    

**Important:** Do not begin development against production endpoints until you have received your approved credentials. You can review the API documentation at [developers.getcount.com](https://developers.getcount.com) while waiting for approval.

### Required Headers

Every authenticated API request must include the following headers:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"14dd8c8e-0180-4041-b79a-d84175e3f153","title":"Title"},{"id":"b0b4bde3-d676-4bbf-93c5-55c7dd15b736","title":"Description"}]'>
  <table-row>
    <table-cell>Header</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>x-client-id</table-cell>
    <table-cell>Your partner Client ID</table-cell>
  </table-row>
  <table-row>
    <table-cell>x-timestamp</table-cell>
    <table-cell>Current Unix timestamp (seconds)</table-cell>
  </table-row>
  <table-row>
    <table-cell>x-signature</table-cell>
    <table-cell>HMAC-SHA256 signature (see below)</table-cell>
  </table-row>
  <table-row>
    <table-cell>Content-Type</table-cell>
    <table-cell>application/json</table-cell>
  </table-row>
  <table-row>
    <table-cell>Authorization</table-cell>
    <table-cell>Bearer (required for data endpoints only)</table-cell>
  </table-row>
</Table>

### Computing the HMAC Signature

The signature is an HMAC-SHA256 hash, using your **Client Secret** as the key, applied to a base string with the following format:

:::

**Four components, separated by colons:**

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"e7d3da1e-5c4a-49fe-8940-399a5f828de5","title":"Title"},{"id":"af8d9a97-bc8a-46c7-a193-f5f8a147d50c","title":"Description"}]'>
  <table-row>
    <table-cell>Component</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>METHOD</table-cell>
    <table-cell>HTTP method in uppercase: GET, POST, PUT, PATCH</table-cell>
  </table-row>
  <table-row>
    <table-cell>path</table-cell>
    <table-cell>The endpoint path without the /partners prefix (e.g., /chart-of-accounts, /grant-access-token)</table-cell>
  </table-row>
  <table-row>
    <table-cell>timestamp</table-cell>
    <table-cell>The same Unix timestamp sent in the x-timestamp header</table-cell>
  </table-row>
  <table-row>
    <table-cell>bodyHash</table-cell>
    <table-cell>SHA-256 hash of the JSON request body (for POST, PUT, PATCH). Empty string for GET requests.</table-cell>
  </table-row>
</Table>

**Important:** The colon separators are always present, even when `bodyHash` is empty. A GET request base string ends with a trailing colon.

### Examples

**POST request** (e.g., exchanging an authorization code):

Base string: POST:/grant-access-token:1772571261:a1b2c3d4e5f6...

Where the body hash is computed as:

SHA-256(JSON.stringify(requestBody))

**GET request** (e.g., fetching chart of accounts):

Base string: GET:/chart-of-accounts:1772571261:

Note the trailing colon — `bodyHash` is an empty string, but the colon separator remains.

### Code Example (Node.js)

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>const crypto = require('crypto');</CodeLine>
  <CodeLine>function signRequest({ method, path, timestamp, body, clientSecret }) {</CodeLine>
  <CodeLine>  let bodyHash = '';</CodeLine>
  <CodeLine>  if (['POST', 'PUT', 'PATCH'].includes(method)) {</CodeLine>
  <CodeLine>    bodyHash = crypto.createHash('sha256')</CodeLine>
  <CodeLine>      .update(JSON.stringify(body))</CodeLine>
  <CodeLine>      .digest('hex');</CodeLine>
  <CodeLine>  }</CodeLine>
  <CodeLine>  const baseString = `${method}:${path}:${timestamp}:${bodyHash}`;</CodeLine>
  <CodeLine>  return crypto.createHmac('sha256', clientSecret)</CodeLine>
  <CodeLine>    .update(baseString)</CodeLine>
  <CodeLine>    .digest('hex');</CodeLine>
  <CodeLine>}</CodeLine>
  <CodeLine>// GET example</CodeLine>
  <CodeLine>const signature = signRequest({</CodeLine>
  <CodeLine>  method: 'GET',</CodeLine>
  <CodeLine>  path: '/chart-of-accounts',   // NOT /partners/chart-of-accounts</CodeLine>
  <CodeLine>  timestamp: Math.floor(Date.now() / 1000),</CodeLine>
  <CodeLine>  body: null,</CodeLine>
  <CodeLine>  clientSecret: 'your_client_secret'</CodeLine>
  <CodeLine>});</CodeLine>
  <CodeLine>// POST example</CodeLine>
  <CodeLine>const signature = signRequest({</CodeLine>
  <CodeLine>  method: 'POST',</CodeLine>
  <CodeLine>  path: '/grant-access-token',</CodeLine>
  <CodeLine>  timestamp: Math.floor(Date.now() / 1000),</CodeLine>
  <CodeLine>  body: { grantType: 'authorization_code', code: 'abc123' },</CodeLine>
  <CodeLine>  clientSecret: 'your_client_secret'</CodeLine>
  <CodeLine>});  </CodeLine>
</CodeBlock>

Common Mistakes

*   Using the full URL path (`/partners/chart-of-accounts`) instead of the relative path (`/chart-of-accounts`)
    
*   Omitting the trailing colon on GET requests
    
*   Including `client_id` or `client_secret` in the request body (these should only be in headers / used for HMAC)
    
*   Hashing the body for GET requests instead of using an empty string
    

### Prerequisites Checklist

Before submitting the form, make sure you have:

*   A clear understanding of your integration use case
    
*   Reviewed the [COUNT API documentation](https://developers.getcount.com)
    
*   A callback/redirect URI ready for your OAuth flow
    
*   An estimated timeline for your integration launch

API Access Credentials

API Reference

### Description

The Authorization section facilitates the OAuth 2.0 flow, enabling third-party applications to request access to a user’s COUNT account. This process ensures that users can securely authenticate, consent to data sharing, and allow external applications to act on their behalf.

### 🔁 Authorization Flow Overview:

COUNT uses an OAuth 2.0 Authorization Code flow to grant your application access to a user’s workspace. The flow works as follows:

Initiate — Your app redirects the user to COUNT’s authorization page.

User Login & Consent — The user logs in to COUNT and selects a workspace to authorize.

Callback — COUNT redirects back to your redirectUri with an authorization code and state.

Token Exchange — Your server exchanges the authorization code for an access token and refresh token.

API Access — Use the access token to make authenticated API requests on behalf of the user.

Important: Your redirect URI must not contain query parameters. If you need to pass context through the flow, use the state parameter.

### Purpose

The Authorization flow allows your application to integrate with COUNT by:

Initiating the process: Calling /auth2/authorize-initiate from your client application to generate the login redirect URL.

Exchanging the authorization code: After user consent, the application exchanges the authorization code received in the redirect for an access token using the /partners/grant-access-token endpoint.

This OAuth 2.0 process ensures secure, token-based access, allowing the application to perform actions (such as posting transactions or retrieving account data) on behalf of users without compromising their credentials.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Note:</p>
  <p></p>
  <p>All of the stated endpoints and sections are for demonstration purposes only.</p>
  <p></p>
</Callout>

Authorization

A **Chart of Accounts (CoA)** is the structured foundation of a company’s financial system. It is a categorized list of all accounts used to classify and record every financial transaction within a business. These accounts typically fall under five major categories: **Assets**, **Liabilities**, **Equity**, **Income**, and **Expenses**.

Each account in the CoA represents a specific element of the company’s financial structure—such as cash, revenue from sales, payroll expenses, or accounts payable—and plays a critical role in producing accurate financial reports like balance sheets and income statements.

### 🧩 How COUNT Uses the Chart of Accounts

In COUNT, the Chart of Accounts is more than a reference—it’s tightly integrated throughout the system to maintain consistency and control over financial classification. Specifically, accounts from the CoA are **applied directly to:**

*   **Bill line items** – to categorize the expense type for accurate payable tracking.
    
*   **Invoice line items** – to associate revenue with the appropriate income account.
    
*   **Transactions** – to log entries that affect financial balances.
    
*   **Products and services** – to map sales and cost accounts automatically during billing and fulfillment.
    

By standardizing financial categorization at every level, the Chart of Accounts ensures that COUNT users maintain clean books, generate accurate reports, and stay compliant with accounting best practices.

Chart Of Accounts

The Customers API allows partner applications to manage customer records in **COUNT**.Customers represent individuals or organizations that you bill, invoice, or transact with.

This API enables you to:

*   List customers associated with your team
    
*   Retrieve customer details using a UUID
    
*   Create and update customer records
    
*   Search for customers by email
    

All customer data is securely scoped to the authenticated team.

<Divider />

Authentication
--------------

All Customers API endpoints require **both** authentication mechanisms:

### HMAC Authentication

Include the following headers in every request:

*   `x-client-id`
    
*   `x-signature`
    

### OAuth Bearer Token

Include a valid access token obtained via the OAuth flow:

Authorization: Bearer YOUR\_ACCESS\_TOKEN

Requests missing either authentication method will be rejected.

<Divider />

Customer Identification
-----------------------

*   All customers are identified using **UUIDs**
    
*   Integer or internal IDs are not exposed to partner applications
    
*   UUIDs are returned in all customer-related responses and must be used in subsequent requests
    

<Divider />

Email Uniqueness
----------------

*   Customer email addresses must be **unique within a team**
    
*   Attempting to create a customer with an existing email will result in an error
    
*   Use the **Find Customer by Email** endpoint to check for existing customers before creation
    

<Divider />

Addresses
---------

Customers can have both:

*   **Billing Address**
    
*   **Shipping Address**
    

Each address supports the following fields:

*   `street`
    
*   `city`
    
*   `state`
    
*   `zipCode`
    
*   `country`
    

<Divider />

Contacts
--------

*   A customer may have multiple contacts
    
*   One contact can be marked as the **primary contact**
    
*   Contacts include name, email, phone number, and primary status
    

<Divider />

Available Endpoints
-------------------

Use the endpoints below to manage customers:

*   **List Customers** – Retrieve all customers for your team
    
*   **Get Customer** – Retrieve a customer by UUID
    
*   **Create Customer** – Create a new customer record
    
*   **Update Customer** – Update an existing customer
    
*   **Find Customer by Email** – Search for a customer using an email address

Customers

A **Vendor** in COUNT represents any external party your business interacts with for goods, services, or contractual work. This can include **merchants**, **suppliers**, or **independent contractors**. Vendors are a critical part of the accounting process, especially when managing expenses, bills, and procurement workflows.

COUNT helps you manage vendor details such as contact information, tax identifiers, payment accounts, and associated addresses. These vendor records can then be used across other accounting features like **bills**, **transactions**, and **reporting**.

Vendors

The Products & Services API allows partner applications to retrieve product and service information from **COUNT**.Products are used as line items when creating invoices and define pricing, accounting behavior, and revenue categorization.

Both physical products and services are managed through this API.

<Divider />

Authentication
--------------

All product endpoints require:

*   **HMAC Authentication** (`x-client-id`, `x-signature`)
    
*   **OAuth Bearer Token**
    

<Divider />

Product Characteristics
-----------------------

Each product includes:

*   A unique UUID
    
*   Pricing information
    
*   Currency
    
*   Status (active or inactive)
    
*   An associated category account for accounting
    

Products must be correctly configured in COUNT before they can be used in invoices.

<Divider />

Product Categories
------------------

*   Every product must have a **category account**
    
*   Category accounts determine how revenue is recorded
    
*   Products without a category cannot be used in invoice creation
    

This is enforced at the API level.

<Divider />

Products vs Services
--------------------

COUNT does not distinguish between products and services at the API level:

*   Both are treated as products
    
*   Pricing method determines behavior
    
*   Services typically use quantity-based pricing
    

<Divider />

Usage in Invoices
-----------------

When creating invoices:

*   Products are referenced by UUID
    
*   Quantity and price are provided per line item
    
*   Taxes are explicitly defined per product line
    

Products define the financial foundation of every invoice.

<Divider />

Available Endpoints
-------------------

Use the endpoints below to work with products:

*   **List Products**
    
*   **Get Product**
    
*   **Find Product by Name**

Products & Services

The Transactions API allows partner applications to create, manage, and retrieve financial transactions in **COUNT**. Transactions represent the movement of money in and out of accounts — they are the primary records that drive financial reporting, reconciliation, and bookkeeping.

This API supports **fully automated financial workflows**, including:

*   Syncing bank transactions from external banking or fintech platforms
    
*   Recording expenses and income from POS, e-commerce, or payment systems
    
*   Categorizing transactions with accounts, vendors, customers, and tags
    
*   Building real-time dashboards and financial analytics from transaction data
    

Transactions created through this API behave the same as transactions created in the COUNT UI.

<Divider />

### Authentication

All transaction endpoints require **both** authentication mechanisms:

*   **HMAC Authentication**
    
*   Headers: <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-client-id`</span>, <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-signature`</span>, <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-timestamp`</span>
    
*   **OAuth Bearer Token**
    
*   <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`Authorization: Bearer YOUR_ACCESS_TOKEN`</span>
    

Requests missing either authentication method will be rejected.

<Divider />

### Transaction Types

Transactions are categorized by the direction and nature of money movement:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"8bbfdc6b-4eeb-466f-b667-94e22b03c39f","title":"Title"},{"id":"89d446db-f2e2-46b1-b018-d3968e4f966c","title":"Description"}]'>
  <table-row>
    <table-cell>Type</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>EXPENSE</table-cell>
    <table-cell>Money going out — purchases, bills, operational costs</table-cell>
  </table-row>
  <table-row>
    <table-cell>INCOME</table-cell>
    <table-cell>Money coming in — sales, payments received, revenue</table-cell>
  </table-row>
  <table-row>
    <table-cell>TRANSFER</table-cell>
    <table-cell>Money moving between accounts — internal transfers</table-cell>
  </table-row>
  <table-row>
    <table-cell>JOURNAL</table-cell>
    <table-cell>Accounting adjustments created via journal entries</table-cell>
  </table-row>
</Table>

<Divider />

### Transaction Structure

Each transaction consists of:

*   **Core fields** — amount, date, description, type, and currency
    
*   **Account reference** — the bank or financial account the transaction belongs to (<span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`accountId`</span>)
    
*   **Category** — a Chart of Accounts entry for categorization (<span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`categoryAccountId`</span>)
    
*   **Relationships** — optional links to a vendor, customer, or tags
    
*   **Status flags** — reviewed, excluded, pending, split
    

All entity references use UUIDs.

<Divider />

### Categorization & Tagging

Transactions support rich categorization:

*   **Category Account** — maps the transaction to a Chart of Accounts entry for reporting
    
*   **Vendor** — associates the transaction with a vendor (for expenses)
    
*   **Customer** — associates the transaction with a customer (for income)
    
*   **Tags** — flexible labels for grouping, filtering, and reporting (e.g. department, project, location)
    

Uncategorized transactions will appear in COUNT's review queue.

<Divider />

### Filtering & Pagination

The List All Transactions endpoint supports filtering by:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"d4df55db-752e-4ec6-9345-0716fb80ec19","title":"Title"},{"id":"693fb12c-8412-4db0-b8eb-feb1a5f9dbc4","title":"Description"},{"id":"cd0aaccc-a65d-4e8d-8ea7-69c7c3c55e13","title":"Title"}]'>
  <table-row>
    <table-cell>Filter</table-cell>
    <table-cell>Type</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>page</table-cell>
    <table-cell>number</table-cell>
    <table-cell>Page number (default: 1)</table-cell>
  </table-row>
  <table-row>
    <table-cell>limit</table-cell>
    <table-cell>number</table-cell>
    <table-cell>Results per page (default: 25)</table-cell>
  </table-row>
  <table-row>
    <table-cell>startDate</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter from date (YYYY-MM-DD)</table-cell>
  </table-row>
  <table-row>
    <table-cell>endDate</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter to date (YYYY-MM-DD)</table-cell>
  </table-row>
  <table-row>
    <table-cell>type</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter by transaction type</table-cell>
  </table-row>
  <table-row>
    <table-cell>accountId</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Filter by bank account UUID</table-cell>
  </table-row>
  <table-row>
    <table-cell>visibility</table-cell>
    <table-cell>string</table-cell>
    <table-cell>Set to firm-team (required)</table-cell>
  </table-row>
</Table>

<Divider />

### Required Dependencies

Before creating transactions, ensure the following exist in COUNT:

*   **Chart of Accounts** — at least two accounts: one for the bank/financial account (<span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`accountId`</span>) and one for categorization (<span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`categoryAccountId`</span>)
    
*   **Vendors** (optional) — for associating expenses with vendors
    
*   **Customers** (optional) — for associating income with customers
    
*   **Tags** (optional) — for categorization and reporting
    

<Divider />

### Available Endpoints

Use the endpoints below to work with transactions:

*   **List All Transactions** — retrieve transactions with pagination and filters
    
*   **Create Transaction** — record a new financial transaction
    
*   **Update Transaction** — modify an existing transaction
    
*   **Delete Transaction** — remove a transaction

Transactions

The Invoices API allows partner applications to create, list, retrieve, update, and delete invoices and related documents in **COUNT**.

Invoices are a core entity used to represent billable work, sales, or services provided to customers. This API supports **automated billing workflows**, including:

*   Listing and filtering invoices (pagination, dates, customer, draft flag, type, search)
*   Creating invoices from external systems (CRM, job management, POS)
*   Credit memos (`invoiceType: 'memo'`) with apply-to-invoice flows
*   Attachments (URL-based or multipart upload)
*   Shareable **public** payment links
*   Recurring invoice templates (separate `/partners/recurring-invoice-templates` routes)
*   Draft and approved lifecycles, send, and approve actions

Invoices created through this API behave the same as invoices created in the COUNT UI.

<Divider />

Authentication
--------------

All **`/partners/invoices`** endpoints require **both** authentication mechanisms:

*   **HMAC Authentication** — headers: `x-client-id`, `x-signature`
*   **OAuth Bearer Token** — `Authorization: Bearer YOUR_ACCESS_TOKEN`

Requests missing either authentication method will be rejected.

<Divider />

Identifiers (UUIDs)
--------------------

Partner responses **expose `id` as the invoice UUID** (numeric database keys are not returned on invoice objects). Path parameters such as **`{uuid}`** use that same UUID.

If duplicate UUIDs exist for the same workspace (legacy data), the API may respond with **409** until data is corrected.

<Divider />

Invoice Relationships
---------------------

An invoice references other core entities by **UUID**:

*   **Customer** – Who the invoice is billed to (`customerUuid` on create)
*   **Products / Services** – Line items (product UUIDs in the payload)
*   **Tags** – Optional (`tagUuids`)

<Divider />

Derived `status` (Partner API)
------------------------------

On Partner invoice routes, responses include a computed **`status`** field (e.g. `draft`, `approved`, `sent`, `paid`, `partial`, `overdue`, estimate-specific values). Use **`status`** as the primary lifecycle indicator; raw fields (`isDraft`, `isSent`, `paymentStatus`, etc.) remain available.

<Divider />

Invoice Lifecycle (summary)
----------------------------

*   **Draft** – Editable; use `isDraft` / `status` / list filter `isDraft=true`
*   **Approved** – Sent and payment states are modeled via **`status`** and related fields; editing is **field-specific** (invalid updates return **400** with a message, not necessarily one generic "locked" code)
*   **Send** – `POST /partners/invoices/{uuid}/send` after requirements are met

Most automated workflows should create invoices as **approved** when they are ready to post.

<Divider />

Invoice Types
-------------

*   `invoice` – Standard billing document
*   `estimate` – Cost estimate / customer-facing estimate flow
*   `memo` – **Credit memo** (see dedicated **Credit memo** section in this docs project)

(Other product-specific types may exist; use `invoiceType` on create/list as documented in the OpenAPI/section specs.)

<Divider />

Required Dependencies
---------------------

Before creating invoices, ensure the following exist in COUNT:

*   Customers (via Customers API)
*   Products with assigned category accounts
*   Optional tags for categorization

Invoices cannot be created if required references are missing.

<Divider />

Available Endpoints (Partner)
-----------------------------

*   **List invoices** — `GET /partners/invoices`
*   **Create invoice or memo** — `POST /partners/invoices`
*   **Get / update / delete** — `GET | PATCH | DELETE /partners/invoices/{uuid}`
*   **Approve** — `PATCH /partners/invoices/{uuid}/approve`
*   **Send** — `POST /partners/invoices/{uuid}/send`
*   **Attachments** — `POST /partners/invoices/{uuid}/attachments` (JSON URLs), `POST .../attachments/upload` (multipart `documents`)
*   **Public link** — `GET /partners/invoices/{uuid}/public-link`
*   **Credit apply / remove** — `PATCH .../apply-multiple-credit-to-invoice`, `PATCH .../apply-credit-to-multiple-invoices`, `PATCH .../remove-credit`
*   **Audit log** — `GET /partners/invoices/{uuid}/audit-log`
*   **Recurring templates** — under `/partners/recurring-invoice-templates` (list, create, get, patch, delete, pause, resume)

See **Partners documentation** (`docs/partners-docu`) for a single-page summary of the same behavior.

For **credit memos** only (`invoiceType: 'memo'`, apply-to-invoice, list filter `invoiceType=memo`), open the dedicated **Credit memo** page in this API reference (sidebar, or folder `api-reference/credit-memo`).


Invoices

The **Credit memo** Partner API uses the same **`/partners/invoices`** routes as standard invoices. A credit memo is an invoice record with **`invoiceType: 'memo'`**. There is **no** separate base path such as `/partners/credit-memos`.

Credit memos reduce amounts owed on **open invoices** via apply-to-invoice endpoints. Responses include the same derived **`status`** field as invoices (see **Invoices**).

<Divider />

Authentication
--------------

Same as all Partner routes: **HMAC** (`x-client-id`, `x-signature`) plus **Bearer** partner access token.

<Divider />

Create a credit memo
--------------------

**`POST /partners/invoices`**

Set **`invoiceType: 'memo'`** in the JSON body. Shape matches invoice create: customer, products/line items, dates, totals, etc.

Partner UUID helpers on create:

* **`appliedToInvoiceUuid`** — optional; links the memo to an open invoice at creation (instead of internal `appliedToInvoiceId`).
* **`customerUuid`**, product UUIDs on lines, **`tagUuids`** — same as invoice create.

**Recurring:** Credit memos **cannot** be recurring. **`POST /partners/recurring-invoice-templates`** requires **`invoiceType: 'invoice'`** (not `memo`).

<Divider />

List credit memos
-----------------

**`GET /partners/invoices`** with **`invoiceType=memo`**.

Combine with `page`, `limit`, `isDraft`, `status`, `customers`, date range, `search`, etc.

<Divider />

Get, update, delete
-------------------

| Method | Path |
|--------|------|
| `GET` | `/partners/invoices/{uuid}` |
| `PATCH` | `/partners/invoices/{uuid}` |
| `DELETE` | `/partners/invoices/{uuid}` |

`{uuid}` is the memo’s UUID (in Partner JSON, object **`id`** equals that UUID).

<Divider />

Approve and send
----------------

| Method | Path |
|--------|------|
| `PATCH` | `/partners/invoices/{uuid}/approve` |
| `POST` | `/partners/invoices/{uuid}/send` |

Same rules as invoices (non-draft, customer, products required for send where enforced).

<Divider />

Apply credit to invoices
-------------------------

All **`id`** values in bodies are **partner invoice UUIDs** (`id` on invoice/memo objects in API responses).

| Method | Path | Role of `{uuid}` | Body |
|--------|------|-------------------|------|
| `PATCH` | `/partners/invoices/{uuid}/apply-multiple-credit-to-invoice` | **Target invoice** (receiving credit) | `creditMemos: [{ id, amount }]` — each **`id`** is a **credit memo** UUID |
| `PATCH` | `/partners/invoices/{uuid}/apply-credit-to-multiple-invoices` | **Credit memo** | `invoices: [{ id, amount }]` — each **`id`** is a **target invoice** UUID |
| `PATCH` | `/partners/invoices/{uuid}/remove-credit` | Context invoice per implementation | `memoId`: UUID of the credit memo to unapply |

<Divider />

Attachments and public link
---------------------------

Same paths as invoices:

* **`POST /partners/invoices/{uuid}/attachments`** — JSON `{ "attachments": [{ "url", "title?" }] }`
* **`POST /partners/invoices/{uuid}/attachments/upload`** — multipart field **`documents`**
* **`GET /partners/invoices/{uuid}/public-link`** — returns `publicToken`, `publicUrl`

<Divider />

Audit log
---------

**`GET /partners/invoices/{uuid}/audit-log`**

<Divider />

Errors and UUIDs
----------------

Ambiguous invoice UUID in a workspace (legacy duplicates) can yield **409** until data is migrated. Invalid field updates typically return **400** with a message.


Credit memo

A **Bill** in COUNT represents an expense your business has received from a vendor but has not yet paid. Bills are an essential part of managing **accounts payable**, helping businesses track outstanding obligations and organize their expense data accurately.

Each bill:

*   **Belongs to a vendor**, who issued the bill for products or services provided.
    
*   **Contains one or more line items**, where each line item:
    
*   Has a specified **amount**, **description**, and **quantity**.
    
*   Can be categorized using a **chart of account** (i.e., expense category).
    
*   Can optionally be associated with a specific **customer** or **project** for tracking billable expenses.
    

This structure ensures businesses maintain clear financial records and can generate detailed reports by vendor, category, project, or customer.

Bills

The Journal Entries API allows partner applications to create, manage, and retrieve journal entries in **COUNT**. Journal entries are the fundamental building blocks of double-entry accounting, used to record financial transactions that affect two or more accounts simultaneously.

This API supports **fully automated accounting workflows**, including:

*   Recording accruals and deferrals from external systems
    
*   Creating adjusting entries at period-end
    
*   Syncing manual journal entries from third-party accounting tools
    
*   Automating recurring entries for prepaid expenses, depreciation, and amortization
    

Journal entries created through this API behave the same as entries created in the COUNT UI.

### Authentication

All journal entry endpoints require **both** authentication mechanisms:

*   **HMAC Authentication**
    
*   Headers: <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-client-id`</span>, <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-signature`</span>, <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`x-timestamp`</span>
    
*   **OAuth Bearer Token**
    
*   <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`Authorization: Bearer YOUR_ACCESS_TOKEN`</span>
    

Requests missing either authentication method will be rejected.

<Divider />

### Double-Entry Accounting

Every journal entry must follow the fundamental accounting rule:

*   **Total Debits = Total Credits**
    
*   Each entry must have at least **two line items**
    
*   One line item must have a debit amount, and at least one must have a credit amount
    
*   Unbalanced entries will be rejected with a <span style="color:rgba(228, 228, 228, 0.92);background-color:color(srgb 0.894118 0.894118 0.894118 / 0.0368628)">`400`</span> error
    

<Divider />

### Journal Entry Structure

A journal entry consists of:

*   **Header** — date, description, memo, and status
    
*   **Line Items (entries)** — each referencing an account UUID with a debit or credit amount
    

Each line item maps to a Chart of Accounts entry. Accounts must exist before they can be referenced in journal entries.

<Divider />

### Common Use Cases

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"5098f1ce-2511-485e-88ac-3cb8663d5ba7","title":"Title"},{"id":"464e0cfa-57a9-41d5-bc4f-44e8335011d3","title":"Description"}]'>
  <table-row>
    <table-cell>Use Case</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>Accruals</table-cell>
    <table-cell>Record revenue or expenses before cash changes hands</table-cell>
  </table-row>
  <table-row>
    <table-cell>Adjusting Entries</table-cell>
    <table-cell>Correct or adjust account balances at period-end</table-cell>
  </table-row>
  <table-row>
    <table-cell>Depreciation</table-cell>
    <table-cell>Record periodic asset depreciation</table-cell>
  </table-row>
  <table-row>
    <table-cell>Reclassification</table-cell>
    <table-cell>Move amounts between accounts</table-cell>
  </table-row>
  <table-row>
    <table-cell>Intercompany Entries</table-cell>
    <table-cell>Record transactions between related entities</table-cell>
  </table-row>
  <table-row>
    <table-cell>Opening Balances</table-cell>
    <table-cell>Set initial account balances when onboarding</table-cell>
  </table-row>
</Table>

<Divider />

### Required Dependencies

Before creating journal entries, ensure the following exist in COUNT:

*   **Chart of Accounts** — all referenced accounts must exist (via Chart of Accounts API)
    
*   Account UUIDs are used to identify debit and credit targets
    

Journal entries cannot be created if referenced accounts are missing.

<Divider />

### Available Endpoints

Use the endpoints below to work with journal entries:

*   **List All Journal Entries** — retrieve all entries with pagination and filters
    
*   **Create Journal Entry** — create a new balanced journal entry
    
*   **Update Journal Entry** — modify an existing entry
    
*   **Delete Journal Entry** — remove a journal entry

Journal Entries

The Tags API allows partner applications to retrieve and search tags from **COUNT**.Tags are used to categorize and organize records such as invoices, transactions, and reports.

Tags are commonly used for:

*   Payment method classification (Cash, Check, Credit Card)
    
*   Location or tax jurisdiction tracking
    
*   Internal reporting and grouping
    

Tags are managed in the COUNT UI and referenced by partner integrations.

<Divider />

Authentication
--------------

All tag endpoints require:

*   **HMAC Authentication** (`x-client-id`, `x-signature`)
    
*   **OAuth Bearer Token**
    

<Divider />

Tag Characteristics
-------------------

*   Tags are **read-only** via the partner API
    
*   Tags are identified by **UUID**
    
*   Tags may optionally belong to one or more tag groups
    
*   Tag names are user-configurable in COUNT
    

<Divider />

Common Tag Types
----------------

Typical tag use cases include:

*   **Payment Method Tags**
    
    *   Cash
        
    *   Check
        
    *   Credit Card
        
    *   Invoice
        
*   **Location / Tax Tags**
    
    *   Jurisdiction or location-based identifiers
        
    *   Often prefixed with a location code
        

<Divider />

Tag Usage in Invoices
---------------------

Tags are most commonly used when creating invoices to:

*   Indicate payment method
    
*   Assign tax location
    
*   Support reporting and reconciliation
    

Invoices may include multiple tags.

<Divider />

Tag Search Behavior
-------------------

*   Tag search is case-insensitive
    
*   Matching is based on name prefixes
    
*   Designed to support flexible lookup without exact matches
    

<Divider />

Available Endpoints
-------------------

Use the endpoints below to work with tags:

*   **List Tags**
    
*   **Get Tag**
    
*   **Find Tag by Name**

Reports

### Webhooks

Partner applications can **subscribe** to workspace events (customers, vendors, transactions, invoices, bills). COUNT delivers JSON **outbound** HTTP `POST` requests to your **HTTPS** callback URL when a subscribed event occurs.

Subscriptions are scoped to the **authorized workspace** (from the partner access token). Deliveries are processed **asynchronously** (queue + worker). Only subscriptions with `status: active` receive deliveries.

<Divider />

Authentication
--------------

All webhook subscription endpoints require:

*   **HMAC authentication** — `x-client-id`, `x-signature`, `x-timestamp` (see **Getting Started** / API Access Credentials for the signing algorithm).
    
*   **Partner access token** — `Authorization: Bearer <access_token>` from the OAuth / token exchange flow.
    

Use `Content-Type: application/json` on `POST` and `PATCH` so the request body matches your HMAC **body hash**.

<Divider />

Event names (v1)
----------------

Dot-notation event strings:

*   **Customer:** `customer.created`, `customer.updated`, `customer.deleted`
    
*   **Vendor:** `vendor.created`, `vendor.updated`, `vendor.deleted`
    
*   **Transaction:** `transaction.created`, `transaction.updated`, `transaction.deleted`
    
*   **Invoice:** `invoice.created`, `invoice.updated`, `invoice.deleted`
    
*   **Bill:** `bill.created`, `bill.updated`, `bill.deleted`
    

**Customer** and **vendor** soft-deletes (`isDeleted` false → true) emit **`.deleted`**, not `.updated`.

**Transaction, invoice, and bill** use different hook logic: soft-delete is often an **update**, so you may receive **`.updated`** until a hard **`destroy`** triggers **`.deleted`**. See **When events fire** for the full matrix.

<Divider />

Base path
---------

All subscription management routes share the base path:

**`/partners/webhooks`**

<Divider />

Reference
---------

*   **When events fire** — detailed triggers for customer, vendor, transaction, invoice, and bill (create / update / delete and soft vs hard delete).

Available endpoints
-------------------

*   **List Webhook Subscriptions** — `GET /partners/webhooks`
    
*   **Create Webhook Subscription** — `POST /partners/webhooks`
    
*   **Update Webhook Subscription** — `PATCH /partners/webhooks/{uuid}`
    
*   **Delete Webhook Subscription** — `DELETE /partners/webhooks/{uuid}`
    

For what COUNT sends **to your server**, see **Outbound Deliveries**.


Sections

The Transaction Object

Tab 1

Sections

The Transaction Object

Tab 1Expand all

Ask an AI

Code with AI

Tab 1