Overview

This guide explains how to use query parameters in Merge’s Accounting API to return a more focused set of data for your end users.

In many accounting integrations, your product does not need every Account, Item, Contact, Customer, Vendor, or other “master” data object available in the customer’s accounting platform. Query parameters help you narrow API responses so your application can power cleaner configuration, mapping, and setup experiences.

Merge’s list endpoints support model-specific query parameters. For example, the Accounting /accounts endpoint supports filters such as company_id, name, account_number, status, and others, while /items and /contacts expose their own relevant filters.

Why should I consider using query params?

Your product likely has an integration settings page where customers configure how data from their accounting system should map into your application.

For example, your settings page may ask a customer to select specific "master" data:

• Accounts from their chart of accounts

• Items or products

• Contacts (customers or vendors)

• Tracking categories (departments, classes, or locations)

In practice, your product probably only cares about a subset of these records. For example, your customer may have hundreds of Accounts in their chart of accounts, but your product may only need the revenue account, expense account, or clearing account relevant to your workflow.

Without filtering, your customer may need to search through a very large dropdown. That can make the integration setup experience harder to use, slower to configure, and more error-prone.

Query parameters let you reduce the amount of data shown to your customer so your mapping experience is easier to complete.

Common query params to use

The most common query parameters to consider for mapping and integration settings experiences are company_id and name.

company_id

In Merge’s Accounting API, Company maps to the concept of an accounting entity. This is especially important for multi-entity accounting systems, such as NetSuite and Sage Intacct.

For these systems, your product will usually only care about data for one entity at a time. For example, if a customer is configuring your integration for a specific subsidiary, business unit, or entity, you may only want to show Accounts, Items, Contacts, or other records relevant to that entity.

The company_id query parameter lets you filter supported Accounting API list responses to records associated with a specific Company.

Example:

GET /api/accounting/v1/accounts?company_id={company_id}

company_id=null

Some Merge objects may not be associated with a specific Company. If an object has no company, that means the object applies across all companies.

Because of this, the most integration-agnostic implementation is usually to make two requests and combine the results in your application:

GET /api/accounting/v1/accounts?company_id={company_id}

and:

GET /api/accounting/v1/accounts?company_id=null

This approach helps account for both:

1. Records that are specific to the selected company/entity.

2. Records that are shared across all companies/entities.

That makes your integration more resilient across accounting platforms. Some integrations may associate records directly to an entity, while others may expose shared records that do not have a company value.

name

Another common query parameter is name. This can be useful when your customer already knows the exact name of the Account, Item, Contact, or other record they want to map.

Set expectations carefully with your customer: the name must be an exact match. It should not be treated like a fuzzy search or “contains” search.

For example, if the Account's name in the third party is Cash - Operating, then searching for Cash will not return the Account name.

Example:

GET /api/accounting/v1/accounts?name=Cash

status

Certain Accounting objects, such as Items and Project, have a status field. This can be useful if your product only needs active or usable records for a mapping or configuration experience.

For example, your product can ignore inactive objects so customers do not accidentally map to records that should no longer be used in their accounting platform.

Example:

GET /api/accounting/v1/projects?status=ACTIVE

category_type for Tracking Categories

If your product is mapping specific types of Tracking Categories, such as departments, classes, or locations, category_type is a great query parameter to use.

Instead of showing every Tracking Category, you can filter the results down to the category type that is relevant to the mapping flow. This makes the configuration experience more focused and helps customers select the right record faster.

Example:

GET /api/accounting/v1/tracking-categories?category_type=DEPARTMENT

Key requirement: account for the initial sync

Before query parameters can return Accounts, Items, Contacts, or other Common Model data, Merge first needs to sync that data from the customer’s accounting platform. This means that even if your product only needs a small number of objects, the customer may still need to wait for the relevant Common Model data to finish syncing before those objects are available in your settings or mapping experience.

Best practice is to just look at the sync status of the Common Models powering your integration settings page. For example, if your product needs Items to power the mapping flow, you do not need to wait for the Invoices Common Model to finish syncing. Instead, you can check the sync status for the specific model your product depends on, such as Items.

See our initial sync best practices for full detail:

• 📄 Initial sync overview and best practices