Company ID Lifecycle

Company IDs in the API are stable, long-lived identifiers.
However, like most large data systems, records can evolve over time.

This page explains how company identifiers behave so you can design integrations that remain reliable even as underlying data changes.

When a company first appears in our system, we create a unique company ID.

This ID is the primary identifier for that company

It is returned in API responses

It should be stored and reused in your integration

Once assigned, the Company ID becomes the canonical reference for that company.

Over time, we may determine that two or more company records actually represent the same real-world organization.

When this happens:

The records are consolidated into a single Company

One Company ID remains the current (active) ID

Other IDs are retained as "previous IDs"

This process ensures that:

Each real-world company is represented only once

Data remains consistent and unified

If your system stores an older company ID that has since been consolidated:

Requests made with that previous ID will still succeed

The API will resolve it to the current Company

The response will include the current Company ID

You do not need to track or manage merges yourself.

This guarantees backward compatibility for stored identifiers.

After Company records are consolidated:

There is only one active Company record

All data from the merged records is combined

No data remains attached exclusively to a previous ID

The Company returned by the API always represents the most complete and up-to-date view available.

To ensure long-term stability of your integrations with the API:

Always store and reference the Company ID returned by the API

If a response contains a different ID than the one requested, update your stored reference

Avoid assuming that IDs never change — instead, rely on API resolution behavior