Compass DocsBy Mesa
Open App

🛡️ Access & Rate Limits

The API is available to every Compass account, and it is protected so that heavy or automated abuse cannot degrade it for everyone else.

Who can call the API

Any logged-in account can create a key (Settings > API) and call the free identity endpoint, GET /v1/me. When a key's credit balance is too low to cover a call, the API returns clearly-marked sample data ("sample": true, plus a Compass-Sample: true response header and a notice opening "NOT REAL DATA" that quotes your balance against the call's price) at 0 credits — synthetic but shaped exactly like live responses, so you can build your integration for free. To receive live data you need a credit balance; credits come from a plan, referral bonuses, or email/telegram verification. See Pricing & Quotas.

Rate limits

Requests are rate limited per account, not per key. The limit is 120 requests per minute on every plan except Team, which gets 300 per minute, and Enterprise, which is capped at 5 requests per second. Minting a second key gives you a second label and a second thing you can revoke; it does not give you a second allowance. Normal integration traffic stays well inside this. If you exceed it, the API returns 429 Too Many Requests. When that happens:

  • Back off and retry. Wait before retrying rather than sending the same burst again.
  • Spread your calls. Even out scheduled jobs instead of firing them all at once.
  • Cache what you can. Store records you have already pulled instead of re-fetching them.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so you can pace yourself without guessing.

Revealing contacts

Rejected keys

Separately from the per-account limit above, rejected authentication is bounded per IP: more than 20 requests a minute carrying a key we cannot resolve returns 429 from that address. It counts failures only, so correct traffic never touches it and a whole office behind one NAT is unaffected. You will only meet it while looping on a key that is mistyped, revoked, or sent to the wrong host. Confirm the key once with GET /v1/me before putting it in a loop.

Revealing a contact's private channels (/v1/people/{id}?include=private) is additionally capped at 600 reveals per hour on a paid plan and 60 per hour on free. This is the same ceiling the app's Unlock button uses, and it sits far above any real integration; it exists to bound bulk enumeration. Re-reading a contact you have already unlocked costs nothing and does not count against it.

Abuse protection

Repeatedly presenting a key we cannot recognise is rate limited by origin, so a credential-guessing loop is cut off quickly. Under-funded keys never reach real data at all, only samples.

Note that requests go directly to the API host; there is no bot-detection or web-application-firewall layer in front of it. What protects the data is the metering described above, not an edge filter.

Fair use

Under-funded keys receive only synthetic samples, and live pulls are metered in credits, so there is no path to pull the real database for free. Bulk and high-volume needs are served by higher plans and, for the largest cases, by Enterprise terms. See Plans & Pricing.