Getting started with the API

Every tool on CIA has a matching API route under /api/v1, authenticated with your API key. The most important thing to know before your first call: credits are deducted before the system fetches data, and if the provider fails a reversing entry is written.

Three things about billing

Charge first, refund after. Credits come off before the call. If you get nothing usable, the system writes a reversing entry. Every movement is one ledger row with the balance after it — nothing changes a balance without leaving a trace.

Prices are per module and come from configuration. Each tool's price lives in the product table and an administrator can change it, so do not hard-code the number in your code. See pricing.

There are no shortcuts. There is no way to run a tool without going through that tool's runner, including over the API.

Immediate tools and background tools

This is what confuses newcomers most.

Fast tools return the result in the response. Slow tools — such as multi-platform ad radar, Google Maps reviews and multi-platform report — run in the background: you receive HTTP 202 Accepted with a run identifier, and read the result later.

Which means your code has to handle both status codes. Writing a loop that only accepts 200 is the single most common first-integration mistake.

Three mistakes on the first call

1. Account not ready. An API key is refused if the account has not verified its email or has not accepted the current privacy version. The error says so explicitly.

2. A parameter outside the allowed set. Many tools accept only certain fixed values for count parameters. Read each tool's documentation rather than guessing.

3. Retrying after a network error with no Idempotency-Key. This is the expensive mistake. See what Idempotency-Key does — read it before writing your first retry loop.

Boundaries the API respects too

The API returns no email addresses, no personal phone numbers, and there is no endpoint that returns a list of people to contact. Phone numbers appear only for businesses in directories such as Google Maps, because that is the business's own public line.

An account that has submitted a block request at the data request page is refused before credits are charged — over the web and over the API alike. See what public data means.

Start small

Call the cheapest tool first to verify authentication and the response shape. Then write the loop. And set an Idempotency-Key from the very first call rather than adding it later.

Frequently asked questions

Is there an unlimited plan? No. Everything is charged in credits, and every tool has a hard limit per run.

Is the data official platform analytics? No. It is an estimate from public data the platform displays to everyone.

Is there a rate limit? There is a per-user limit at the service layer. Design your code to handle a limited response rather than firing calls in bursts.