AggK IDs

AggK IDs are unique identifiers used throughout the AggKnowledge API to identify resources such as companies and people. They follow the Snowflake ID format — 64-bit integers that encode a timestamp, a worker ID, and a sequence number. This design allows IDs to be generated at scale without coordination while remaining roughly time-sortable.

Working with AggK IDs

Because AggK IDs are 64-bit integers, they can exceed the safe integer range of some programming languages and runtimes. For example, JavaScript's Number type can only safely represent integers up to 2⁵³ − 1 (Number.MAX_SAFE_INTEGER), so a 64-bit AggK ID may lose precision when parsed as a Number.

We recommend treating AggK IDs as strings in your application code to avoid precision loss. The exact JSON representation may vary by endpoint and published schema, so use the API specification for the endpoint you are integrating with as the source of truth for the wire type.

If your language or library requires a numeric type, use one that supports the full 64-bit integer range:

Example

Code
{
  "id": "7248056856377851904",
  "name": "Acme Corp"
}

Always store AggK IDs as strings (or an appropriate 64-bit integer type) to avoid subtle bugs caused by integer overflow or precision loss. For equality checks, comparing string IDs is fine. For ordering comparisons or sorting, use a numeric type that supports the full 64-bit range (such as BigInt or int64), or a zero-padded string representation if string ordering is required.