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**.


Webhooks

Blank

Partners

COUNT Developers

Production

Sandbox

Add Account

Add Bill

Add Customer

Add Journal Entry

Add Product

Add Trial Balance

Add Vendor

Exchange Authorization Code

Initiate Authorization

Refresh Token Endpoint

Approve Bill

Delete Bill

The Bill Object

Update Bill

Delete Account

List All Chart of Accounts

The Account Object

Update Account

Delete Customer

Find Customer by Email

Get Customer

List Customers

The Customers Object

Update Customer

Create Invoice

Delete Invoice

Get Invoice

The Invoice Object

Update Invoice

Delete Journal Entry

List All Journal Entries

The Journal Entry Object

Update Journal Entry

Delete Product

Find Product by Name

Get Product

List Products

The Products Object

Update Product

Balance Sheet Report

Create Balance Sheet Report

List Balance Sheet Reports

The Balance Sheet Object

Profit & Loss

Create PnL

List PnL

The PnL Object

Trial Balance

The Trial Balance Object

Create Tag

Create Tag Group

Delete Tag

Delete Tag Group

Find Tag by Name

Get Tag

List Tags

The Tags object

Update Tag

Update Tag Group

Create Transaction

Delete Transaction

List All Transaction

The Transaction Object

Update Transaction

Delete Vendor

List All Vendors

The Vendor Object

Update Vendor

Create Webhook Subscription

Delete Webhook Subscription

List Webhook Subscriptions

Outbound Deliveries

Update Webhook Subscription

When events fire

The Trial Balance API allows partner applications to generate trial balance reports in COUNT. A trial balance is a financial report that lists all general ledger account balances, verifying that total debits equal total credits for a given period.

### This API enables you to:

*   Generate a trial balance report for a specific date range
    
*   Filter by accounts, account types, tags, vendors, customers, and projects
    
*   View debit and credit totals per account
    
*   Choose between accrual and cash basis reporting
    
*   All report data is securely scoped to the authenticated team
    

<Divider />

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

All Trial Balance API endpoints require **both** authentication mechanisms:

### HMAC Authentication

Include the following headers in every request:

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

### Bearer Token

Include the access token in the `Authorization` header:

Authorization: Bearer {access\_token}

<Divider />

Endpoint
--------

GET /partners/reports/trial-balance?startDate=2024-01-01&endDate=2024-12-31&currency=USD

**Method:** `GET` **Path:** `/partners/reports/trial-balance`

**Query Parameters:**

*   `startDate` (YYYY-MM-DD) – required
    
*   `endDate` (YYYY-MM-DD) – required
    
*   `currency` (ISO 4217) – optional

A Balance Sheet is a fundamental financial statement that provides a snapshot of a company's financial position at a specific point in time. It shows what a business owns (assets), what it owes (liabilities), and the residual value belonging to owners (equity). The balance sheet follows the fundamental accounting equation:

**Assets = Liabilities + Equity**

Unlike the Profit & Loss statement which shows performance over a period, the balance sheet is a "point-in-time" snapshot, typically prepared at the end of a month, quarter, or fiscal year.

Purpose and Use Cases
---------------------

The Balance Sheet serves several critical business functions:

### Financial Health Assessment

*   **Liquidity Analysis**: Determine if the company has enough short-term assets to cover short-term liabilities
    
*   **Solvency Evaluation**: Assess the company's ability to meet long-term obligations
    
*   **Capital Structure**: Understand the mix of debt and equity financing
    
*   **Asset Management**: Track how efficiently assets are being utilized
    

### Business Decision Making

*   **Credit Decisions**: Evaluate creditworthiness for loans and credit lines
    
*   **Investment Planning**: Assess capacity for capital investments and expansion
    
*   **Debt Management**: Monitor debt levels and repayment capabilities
    
*   **Working Capital**: Analyze current assets vs. current liabilities for operational efficiency
    

### Stakeholder Communication

*   **Investor Relations**: Demonstrate financial stability and asset base to investors
    
*   **Lender Requirements**: Provide required documentation for loan applications and covenant compliance
    
*   **Acquisition Due Diligence**: Present complete financial position during M&A activities
    
*   **Board Reporting**: Show financial health and resource allocation to board members
    

### Operational Insights

*   **Asset Utilization**: Track fixed assets, depreciation, and capital efficiency
    
*   **Inventory Management**: Monitor inventory levels and turnover
    
*   **Receivables Management**: Analyze accounts receivable aging and collection efficiency
    
*   **Cash Management**: Track cash and cash equivalents for liquidity planning
    

Key Components of a Balance Sheet
---------------------------------

### Assets

Assets are resources owned by the business that have economic value.

#### Current Assets (Short-term, typically convertible to cash within one year)

*   **Cash and Cash Equivalents**: Money in bank accounts and highly liquid investments
    
*   **Accounts Receivable**: Money owed by customers for goods/services delivered
    
*   **Inventory**: Raw materials, work-in-progress, and finished goods
    
*   **Prepaid Expenses**: Payments made in advance for future benefits
    
*   **Short-term Investments**: Securities and investments maturing within one year
    

#### Non-Current Assets (Long-term assets held for more than one year)

*   **Property, Plant & Equipment (PP&E)**: Land, buildings, machinery, vehicles
    
*   **Accumulated Depreciation**: Reduction in value of fixed assets over time
    
*   **Intangible Assets**: Patents, trademarks, goodwill, software
    
*   **Long-term Investments**: Stocks, bonds, and investments held long-term
    
*   **Other Non-Current Assets**: Long-term notes receivable, deferred tax assets
    

### Liabilities

Liabilities are obligations the business owes to external parties.

#### Current Liabilities (Short-term obligations due within one year)

*   **Accounts Payable**: Money owed to suppliers and vendors
    
*   **Short-term Loans**: Bank loans and credit lines due within one year
    
*   **Accrued Expenses**: Expenses incurred but not yet paid (wages, taxes, interest)
    
*   **Deferred Revenue**: Payments received in advance for future delivery
    
*   **Current Portion of Long-term Debt**: The portion of long-term loans due this year
    

#### Non-Current Liabilities (Long-term obligations due after one year)

*   **Long-term Debt**: Bonds, mortgages, and loans with maturity beyond one year
    
*   **Deferred Tax Liabilities**: Taxes owed in future periods
    
*   **Pension Obligations**: Long-term employee retirement commitments
    
*   **Lease Obligations**: Long-term lease commitments
    
*   **Other Long-term Liabilities**: Warranty obligations, environmental liabilities
    

### Equity (Shareholders' Equity / Owner's Equity)

Equity represents the residual interest in assets after deducting liabilities.

*   **Common Stock**: Par value of issued shares
    
*   **Paid-in Capital**: Amount paid by investors above par value
    
*   **Retained Earnings**: Cumulative profits retained in the business
    
*   **Treasury Stock**: Company's own shares repurchased (reduces equity)
    
*   **Other Comprehensive Income**: Unrealized gains/losses not in net income
    

**Equity Calculation:**

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Equity = Assets - Liabilities </CodeLine>
</CodeBlock>

Balance Sheet Structure
-----------------------

### Classified Balance Sheet

Most balance sheets are "classified," meaning assets and liabilities are grouped by time horizon:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>ASSETS</CodeLine>
  <CodeLine>├── Current Assets</CodeLine>
  <CodeLine>│   ├── Cash                           $50,000</CodeLine>
  <CodeLine>│   ├── Accounts Receivable           $125,000</CodeLine>
  <CodeLine>│   ├── Inventory                      $75,000</CodeLine>
  <CodeLine>│   └── Prepaid Expenses               $10,000</CodeLine>
  <CodeLine>│       Total Current Assets                    $260,000</CodeLine>
  <CodeLine>│</CodeLine>
  <CodeLine>├── Non-Current Assets</CodeLine>
  <CodeLine>│   ├── Property & Equipment          $400,000</CodeLine>
  <CodeLine>│   ├── Less: Accumulated Depreciation ($100,000)</CodeLine>
  <CodeLine>│   ├── Intangible Assets              $50,000</CodeLine>
  <CodeLine>│   └── Long-term Investments          $90,000</CodeLine>
  <CodeLine>│       Total Non-Current Assets                $440,000</CodeLine>
  <CodeLine>│</CodeLine>
  <CodeLine>TOTAL ASSETS                                    $700,000</CodeLine>
  <CodeLine>LIABILITIES & EQUITY</CodeLine>
  <CodeLine>├── Current Liabilities</CodeLine>
  <CodeLine>│   ├── Accounts Payable               $50,000</CodeLine>
  <CodeLine>│   ├── Short-term Loans               $30,000</CodeLine>
  <CodeLine>│   └── Accrued Expenses               $20,000</CodeLine>
  <CodeLine>│       Total Current Liabilities               $100,000</CodeLine>
  <CodeLine>│</CodeLine>
  <CodeLine>├── Non-Current Liabilities</CodeLine>
  <CodeLine>│   └── Long-term Debt                $150,000</CodeLine>
  <CodeLine>│       Total Non-Current Liabilities           $150,000</CodeLine>
  <CodeLine>│</CodeLine>
  <CodeLine>├── Equity</CodeLine>
  <CodeLine>│   ├── Common Stock                  $200,000</CodeLine>
  <CodeLine>│   ├── Retained Earnings             $250,000</CodeLine>
  <CodeLine>│   └── Total Equity                            $450,000</CodeLine>
  <CodeLine>│</CodeLine>
  <CodeLine>TOTAL LIABILITIES & EQUITY                      $700,000 </CodeLine>
</CodeBlock>

Important Balance Sheet Concepts
--------------------------------

### The Accounting Equation

The balance sheet must always balance:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Assets = Liabilities + Equity </CodeLine>
</CodeBlock>

If assets increase, either liabilities must increase, equity must increase, or another asset must decrease by the same amount.

### Working Capital

Working capital measures short-term financial health:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Working Capital = Current Assets - Current Liabilities </CodeLine>
</CodeBlock>

Positive working capital indicates the company can cover short-term obligations.

### Net Assets

Net assets represent the book value of the company:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Net Assets = Total Assets - Total Liabilities = Equity </CodeLine>
</CodeBlock>

Common Balance Sheet Ratios
---------------------------

### Current Ratio (Liquidity)

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Current Ratio = Current Assets / Current Liabilities </CodeLine>
</CodeBlock>

*   **Interpretation**: Ratio > 1 means company can cover short-term obligations
    
*   **Healthy Range**: 1.5 to 3.0 (varies by industry)
    

### Quick Ratio (Acid Test)

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Quick Ratio = (Current Assets - Inventory) / Current Liabilities </CodeLine>
</CodeBlock>

*   **Interpretation**: More conservative liquidity measure excluding inventory
    
*   **Healthy Range**: 1.0 or higher
    

### Debt-to-Equity Ratio

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Debt-to-Equity = Total Liabilities / Total Equity </CodeLine>
</CodeBlock>

*   **Interpretation**: Shows proportion of financing from debt vs. equity
    
*   **Lower is Better**: Less than 2.0 is generally considered healthy
    

### Asset Turnover Ratio

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>Asset Turnover = Revenue / Total Assets </CodeLine>
</CodeBlock>

*   **Interpretation**: How efficiently assets generate revenue
    
*   **Higher is Better**: More revenue per dollar of assets
    

### Return on Assets (ROA)

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>ROA = Net Income / Total Assets × 100 </CodeLine>
</CodeBlock>

*   **Interpretation**: Profitability relative to asset base
    
*   **Higher is Better**: More profit generated from assets
    

### Return on Equity (ROE)

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>ROE = Net Income / Shareholders' Equity × 100 </CodeLine>
</CodeBlock>

*   **Interpretation**: Return generated for equity investors
    
*   **Higher is Better**: More efficient use of equity capital
    

Accounting Methods for Balance Sheet
------------------------------------

### Accrual Basis (Standard)

*   **Asset Recognition**: Record when economic benefit is obtained
    
*   **Liability Recognition**: Record when obligation is incurred
    
*   **Most Common**: Required for GAAP and IFRS compliance
    

### Cash Basis (Simplified)

*   **Asset Recognition**: Only cash and items paid for in cash
    
*   **Liability Recognition**: Only obligations that have been paid
    
*   **Limited Use**: Rarely used for balance sheets; mainly for small businesses
    

**Note:** COUNT primarily supports accrual basis for balance sheet reporting, as this provides the most accurate financial position.

Filtering and Customization
---------------------------

The COUNT Partner API allows you to customize balance sheet reports:

### Date Selection

*   **As-of Date**: The specific date for the balance sheet snapshot
    
*   **Comparison Periods**: Generate balance sheets for multiple dates to analyze changes
    

### Account Filtering

*   **By Account Type**: Focus on specific categories (Assets, Liabilities, Equity)
    
*   **By Account Class**: Filter by current vs. non-current classifications
    
*   **By Specific Accounts**: Include/exclude particular chart of accounts
    

### Reporting Options

*   **Comparative Balance Sheets**: Side-by-side comparison of different periods
    
*   **Common-Size Analysis**: Show each item as percentage of total assets
    
*   **Consolidated View**: Combine multiple entities or departments
    

Best Practices for Balance Sheet Analysis
-----------------------------------------

### 1\. Regular Review

*   Generate monthly balance sheets to track trends
    
*   Compare period-over-period to identify significant changes
    
*   Review before major financial decisions
    

### 2\. Trend Analysis

*   **Horizontal Analysis**: Compare line items across multiple periods
    
*   **Vertical Analysis**: Express each item as percentage of total
    
*   **Ratio Trends**: Track key ratios over time
    

### 3\. Cash Management

*   Monitor cash levels for operational needs
    
*   Ensure adequate liquidity for obligations
    
*   Optimize cash reserves vs. investment opportunities
    

### 4\. Asset Management

*   Track depreciation schedules for fixed assets
    
*   Monitor accounts receivable aging
    
*   Optimize inventory levels
    

### 5\. Liability Management

*   Monitor debt levels and debt service requirements
    
*   Ensure current ratio remains healthy
    
*   Plan for upcoming debt maturities
    

### 6\. Data Accuracy

*   Reconcile bank and credit card accounts
    
*   Verify accounts receivable and payable
    
*   Ensure inventory counts are accurate
    
*   Review and adjust accruals
    

Integration with COUNT Partner API
----------------------------------

The COUNT Partner API provides programmatic access to balance sheet generation:

*   **Automated Reporting**: Generate balance sheets on schedule
    
*   **Period-End Reporting**: Automate month-end and year-end balance sheets
    
*   **Multi-Entity Reporting**: Generate balance sheets for multiple organizations
    
*   **Comparative Analysis**: Pull multiple periods for trend analysis
    
*   **Data Export**: Extract balance sheet data for custom analysis
    

Use Cases for API Integration
-----------------------------

### Accounting Firms

*   Generate standardized balance sheets for all clients
    
*   Create automated month-end reporting packages
    
*   Monitor client financial health indicators
    

### Financial Planning Tools

*   Import balance sheet data for forecasting models
    
*   Track actual vs. projected financial position
    
*   Analyze capital structure and financing needs
    

### Business Dashboards

*   Display real-time financial position metrics
    
*   Create executive dashboards with key ratios
    
*   Alert on liquidity or solvency concerns
    

### Lending Platforms

*   Evaluate creditworthiness automatically
    
*   Monitor covenant compliance
    
*   Track collateral value and loan-to-value ratios
    

<Divider />

_Last Updated: February 2026_

The Balance Sheet object represents a comprehensive financial position snapshot at a specific point in time. It contains structured data showing all asset, liability, and equity accounts with their balances, following the fundamental accounting equation: Assets = Liabilities + Equity. The object is returned when you generate a balance sheet report via the COUNT Partner API and includes both summary totals and detailed line items for each account.

The structure follows standard accounting principles, organizing accounts into current and non-current classifications, with automatic calculation of working capital, total assets, total liabilities, and total equity. All monetary values are returned in the specified currency (or the organization's default currency if not specified).

Retrieve a list of all saved balance sheet reports.

Generate a Balance Sheet report for a specific date with optional filtering.

The Profit & Loss (P&L) report, also known as an Income Statement, is one of the most important financial statements for any business. It provides a comprehensive summary of a company’s revenues, costs, and expenses over a specific period of time, ultimately showing whether the business made a profit or incurred a loss during that period.

Purpose and Use Cases
---------------------

The P&L report serves several critical business functions:

### Financial Performance Analysis

*   Track revenue streams to identify which products, services, or revenue sources generate the most income
    
*   Monitor expenses to understand where money is being spent and identify cost-saving opportunities
    
*   Calculate profitability to determine net income (profit) or net loss for the reporting period
    
*   Perform trend analysis by comparing P&L reports across different periods
    

### Business Decision Making

*   Analyze cost structures to support pricing strategies
    
*   Use historical P&L data for budget planning and forecasting
    
*   Support investment and expansion decisions
    
*   Identify areas where expenses are high relative to revenue
    

### Stakeholder Communication

*   Demonstrate financial health to investors
    
*   Provide financial documentation for lenders and credit applications
    
*   Prepare financial data for tax filing
    
*   Report performance to board members and stakeholders
    

### Operational Insights

*   Break down P&L by tags, projects, or categories
    
*   Identify seasonal patterns in revenue and expenses
    
*   Analyze gross and operating margins
    
*   Benchmark performance against industry standards
    

Key Components of a P&L Report
------------------------------

### Revenue (Income)

Sources of income generated during the period:

*   Sales Revenue
    
*   Service Revenue
    
*   Other Income (interest, investments, non-operating income)
    

### Cost of Goods Sold (COGS)

Direct costs associated with producing or delivering products/services:

*   Materials
    
*   Direct Labor
    
*   Manufacturing Overhead
    

### Gross Profit

Formula: Revenue - Cost of Goods Sold

Indicates how efficiently the business produces and sells products or services before operating expenses.

### Operating Expenses

Ongoing costs required to run the business:

*   Salaries and Wages
    
*   Rent and Utilities
    
*   Marketing and Advertising
    
*   Office Expenses
    
*   Professional Services
    
*   Depreciation
    

### Operating Income

Formula: Gross Profit - Operating Expenses

Represents profit from core business operations before interest and taxes.

### Net Income

Formula: Total Revenue - Total Expenses

Represents final profit or loss for the period.

Accounting Methods
------------------

COUNT supports two accounting methods for P&L reporting:

### Accrual Basis (Recommended)

*   Record revenue when earned
    
*   Record expenses when incurred
    
*   Provides a more accurate view of financial performance
    
*   Required for GAAP compliance and standard reporting
    

### Cash Basis

*   Record revenue only when cash is received
    
*   Record expenses only when cash is paid
    
*   Simple and cash-flow focused
    
*   Common for small businesses and tax reporting
    

Filtering and Customization
---------------------------

The COUNT Partner API allows customization of P&L reports:

### Time Period Filtering

*   Define start and end dates
    
*   Monthly, quarterly, annual, or custom ranges
    

### Entity Filtering

*   Filter by tags
    
*   Filter by projects
    
*   Filter by customers
    
*   Filter by vendors
    

### Account Filtering

*   Filter by account types
    
*   Filter by specific accounts
    

### Transaction Status

*   Include only reviewed transactions
    
*   Filter by reconciliation status
    

Common P&L Metrics and Ratios
-----------------------------

### Gross Profit Margin

(Gross Profit / Total Revenue) × 100

### Operating Profit Margin

(Operating Income / Total Revenue) × 100

### Net Profit Margin

(Net Income / Total Revenue) × 100

### Expense Ratio

(Total Expenses / Total Revenue) × 100

Best Practices for P&L Analysis
-------------------------------

### 1\. Regular Review

*   Generate P&L reports monthly
    
*   Compare results against budgets
    
*   Investigate anomalies
    

### 2\. Comparative Analysis

*   Year-over-Year comparisons
    
*   Quarter-over-Quarter trends
    
*   Budget vs Actual comparisons
    

### 3\. Segment Your Data

*   Use tags for department-level P&L
    
*   Analyze by product line or location
    
*   Track project-level profitability
    

### 4\. Watch Key Indicators

*   Gross margin trends
    
*   Operating expense growth
    
*   Revenue growth patterns
    

### 5\. Data Quality

*   Categorize transactions correctly
    
*   Reconcile accounts regularly
    
*   Maintain consistent categorization
    

Integration with COUNT Partner API
----------------------------------

The COUNT Partner API enables:

*   Automated P&L report generation
    
*   Custom dashboards
    
*   Multi-client reporting
    
*   Data integration with BI tools
    
*   Real-time financial insights
    

API Integration Use Cases
-------------------------

### Accounting Firms

*   Automated P&L reporting for clients
    
*   Client portals with live dashboards
    
*   Faster month-end and year-end close
    

### Business Management Platforms

*   Embedded financial analytics
    
*   Consolidated reporting
    
*   Finance visibility for non-accountants
    

### Financial Planning Tools

*   Budget vs actual analysis
    
*   Forecasting and modeling
    
*   Automated variance reports
    

### Industry-Specific Applications

*   Industry-tailored reports
    
*   Benchmarking metrics
    
*   Customized P&L views

Sections

List Balance Sheet Reports

Header Parameters

Query Parameters

Response

Response

Sections

List Balance Sheet Reports

Header Parameters

Query Parameters

Response

Response

Ask an AI

Code with AI