Compass DocsBy Mesa
Open App

🔀 Request Lifecycle

Here is what happens to a single request, from the moment you send it to the moment you get JSON back. This is the same path for every endpoint.

Step by step

  1. You send a request. A standard HTTPS call to a path under https://compass.mesa.so/api/v1, with your key in the Authorization header.
  2. Edge protection checks it. The request passes through rate limiting, bot detection, and a web application firewall. Normal traffic flows straight through. Traffic far beyond normal use is slowed or blocked with a 429.
  3. The key is verified. The server reads the bearer token, hashes it, and looks up the matching account. If the key is missing, malformed, or revoked, the request stops here with a 401.
  4. Scope is checked. The key's scopes decide whether it may read what the endpoint returns. A key without the right scope gets a clear error instead of data.
  5. The call is charged in credits. A data call costs 5 credits, a private contact reveal 10, and /v1/me is free. If your balance is too low, the request stops here with a 402 and nothing is charged.
  6. Data is fetched and shaped. The API reads from the same database as the app, then serializes the result into the people-first shape, removing internal fields.
  7. You get JSON. A 200 with the data, or a clear status code and an { "error": "..." } body if something went wrong. Every response carries a Compass-API-Version header.

What this means for you

  • Send the key on every call. There is no session to keep alive. Each request stands on its own.
  • Handle 429 with backoff. If you are rate limited, wait and retry rather than hammering. See Access & Rate Limits.
  • Read the status code first. It tells you whether to read data or an error. See Errors & Status Codes.
  • Watch your balance. /v1/me reports your live credit balance, and a call with too few credits returns 402. See Pricing & Quotas.