# Funnelfeedr API > Funnelfeedr is a B2B prospecting platform with Nordic organization and contact data. The Funnelfeedr API is a REST API at https://api.funnelfeedr.com/external/v1, authenticated with an account-level API key, for matching organizations and people, reading organizations' target-role contacts and switchboards, and revealing organization and contact details for credits from your own tools and agents. Every lookup and reveal takes an array of 1-25 items and answers per item. Errors are RFC 9457 problem+json with a stable `code`. Credits are spent only by reveals: an organization's details, and a contact's email and phone. ## Instructions Rules for AI agents calling the Funnelfeedr API on a user's behalf: 1. Only reveals spend credits: `POST /contacts/reveal`, and `POST /organizations/match`, `POST /people/match` or `POST /organizations/switchboards/match` with `reveal` set and `dryRun` false. Matching, contacts, switchboards and the balance are free. 2. Before any reveal, send the same request with `dryRun: true`, show the user the quoted cost (`creditsQuoted`), and reveal only after they approve it. 3. Always set `maxCredits` on a reveal to the amount the user approved. A request that would cost more fails with `credit_cap_exceeded` and spends nothing. 4. Always send an `Idempotency-Key` header (a new UUID per logical request) on a call that spends, and on every `POST /contacts/reveal`, dry runs included. Reuse the same key, with the same body, only to retry that same request. 5. Never loop reveals one item at a time and never reveal the same contact or organization twice. Batch up to 25 items in one request. 6. On `402 insufficient_credits`, stop and tell the user. Nothing was spent; do not retry until they have topped up. 7. On an `ambiguous` match, ask the user which candidate they mean, or pick one by `id` from your own data. Never reveal every candidate. 8. On `429 rate_limited`, wait the number of seconds in `Retry-After` before retrying. Retry other errors only when the body says `"retryable": true`. 9. Read the key from the `FUNNELFEEDR_API_KEY` environment variable. Never print, log or commit it, and never send it from a browser or mobile app. ## Get started - [Funnelfeedr API](https://funnelfeedr.com/developers.md): Match organizations and people against Funnelfeedr's Nordic B2B data, find the right contacts and switchboards, and reveal organization and contact details from your own systems and AI agents, with an account-level API key. - [Quickstart](https://funnelfeedr.com/developers/quickstart.md): Create an API key, check your credit balance, match organizations and a person, and reveal contact details safely — in a few curl calls. - [Authentication](https://funnelfeedr.com/developers/authentication.md): API keys belong to the account, can call every endpoint including the ones that spend credits, and are sent as a bearer token. How to create, roll and revoke them, and where they must never go. - [Guidance for AI agents](https://funnelfeedr.com/developers/agent-guidance.md): Rules for an AI agent that calls the Funnelfeedr API on someone's behalf — which calls spend credits, how to quote before revealing, and how to stop safely. ## Using the API - [Matching organizations and people](https://funnelfeedr.com/developers/matching.md): How organizations/match, organizations/switchboards/match and people/match find records, which organization fields are free and which are revealed for credits, which contacts organizations/contacts/match returns, every status they answer with, and full JSON for a hit, no match, an ambiguous match and running out of credits. - [Credits & reveal](https://funnelfeedr.com/developers/credits-and-reveal.md): What spends credits, how to get an exact quote with dryRun, how maxCredits caps a request, how reveals are charged all-or-nothing and only for what they unmask, and what an organization's details cost. - [Batching](https://funnelfeedr.com/developers/batching.md): Every lookup and reveal takes an array of 1 to 25 items and answers each one separately, in order, with your ref echoed back. - [Pagination](https://funnelfeedr.com/developers/pagination.md): Organizations' contacts page per organization inside a batch, with a limit of 1 to 50 and an opaque cursor per item; follow each result's nextCursor until it is null. - [Idempotency](https://funnelfeedr.com/developers/idempotency.md): Send an Idempotency-Key on every call that spends credits so a retry returns the first answer instead of charging twice. - [Rate limits](https://funnelfeedr.com/developers/rate-limits.md): Per-key limits in one-minute windows across three buckets, reported in RateLimit-Policy and RateLimit headers, with Retry-After on a 429. - [Errors](https://funnelfeedr.com/developers/errors.md): Every error is RFC 9457 problem+json with a stable code and a retryable flag. The full catalog, with what to do about each code. ## Reference - [API reference](https://funnelfeedr.com/developers/api-reference.md): Every endpoint, parameter, response and error of the Funnelfeedr API, rendered from the OpenAPI spec. - [Changelog](https://funnelfeedr.com/developers/changelog.md): Changes to the Funnelfeedr API, newest first. - [OpenAPI spec](https://funnelfeedr.com/developers/openapi.json): The machine-readable contract. operationIds are verb_noun and work as tool names. - [Full documentation](https://funnelfeedr.com/developers/llms-full.txt): Every page above in one markdown file. ## Optional - [Funnelfeedr MCP server](https://funnelfeedr.com/support/mcp-overview): For Claude, ChatGPT and other MCP clients. It signs in per user with OAuth; API keys do not work there.