Identifiers
Every company endpoint accepts one or more of these identifiers. They are interchangeable as inputs, but not equal in reliability:
| Identifier | Reliability | Notes |
|---|---|---|
Company id | Highest | Stable AggKnowledge ID. Store it once matched. |
website domain | High | Normalized root domain (use the Normalize website URL utility first). |
socialProfile | High | Company LinkedIn page URL, using either the vanity name or the numeric company ID. |
name | Lowest | Names collide (“Apex”, “Mercury”…). Use Match, which returns scored candidates; never assume a unique hit. |
Warning: When matching by name alone, always review match candidates — prefer domain or LinkedIn URL whenever you have them.
Which one should I store?#
Always persist the company id after the first successful match. Domains and LinkedIn URLs change and names collide — the id is the only stable primary key. Treat the domain and LinkedIn URL as strong acquisition keys, and name as a last resort that always needs Match.
Warning: The company
id is 64-bit. v3 returns it as a JSON string; store and compare it as a string. v2 returns it as a JSON number, which carries the same precision trap as personId: JSON.parse silently rounds values above Number.MAX_SAFE_INTEGER (2^53 − 1), so on v2 parse IDs with a BigInt-aware reviver. Never convert an ID with Number() or parseInt().