Get started

Quickstart

Create an API key, check your credit balance, match organizations and a person, and reveal contact details safely — in a few curl calls.

This takes about five minutes. You need a Funnelfeedr account with API access and an admin who can create keys.

1. Get a key

Make sure the API is enabled for your account. If Settings → API keys in the app shows a request-access screen, request it there; we enable it per account.
In Settings → API keys, choose Create key. Name it after the integration ("CRM sync", "Lead agent"). Every key can call every endpoint, including the ones that spend credits.
Copy the key. It is shown once; Funnelfeedr stores only a hash of it.
Put it in an environment variable on the machine that will call the API:

export FUNNELFEEDR_API_KEY="ff_live_..."

Keep the key server-side. It must never reach a browser, a mobile app or a git repository — see Authentication.

2. Make your first call

Check the account's credit balance. It is free.

curl https://api.funnelfeedr.com/external/v1/credits \
  -H "Authorization: Bearer $FUNNELFEEDR_API_KEY"

{
  "included": 300,
  "purchased": 112.4,
  "total": 412.4
}

included is the plan's recurring allowance and is spent first; purchased credits do not reset; total is what a reveal can spend right now. The same total comes back in the Funnelfeedr-Credits-Remaining header.

A 401 means the key is wrong; a 403 with feature_not_enabled means API access is not switched on yet. See Errors.

3. Match organizations

Look organizations up by domain, org number, LinkedIn page or Funnelfeedr id. Matching is free. ref is yours: it comes back unchanged so you can line results up with your own rows.

curl https://api.funnelfeedr.com/external/v1/organizations/match   -H "Authorization: Bearer $FUNNELFEEDR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "items": [
      { "ref": "crm-1001", "domain": "nordviklogistik.se" },
      { "ref": "crm-1002", "orgNumber": "5590123456", "countryCode": "SE" },
      { "ref": "crm-1003", "domain": "unknown-startup.se" }
    ]
  }'

{
  "results": [
    {
      "ref": "crm-1001",
      "status": "matched",
      "matchedBy": "domain",
      "organization": {
        "id": "6f9d2f1e-6f37-4a2f-9a3e-1b5c0f4d7e21",
        "name": "Nordvik Logistik AB",
        "detailsRevealed": false,
        "countryCode": "SE",
        "domain": "nordviklogistik.se",
        "city": "Göteborg",
        "legalForm": "Aktiebolag",
        "foundedYear": 2004,
        "url": "https://app.funnelfeedr.com/organizations/6f9d2f1e-6f37-4a2f-9a3e-1b5c0f4d7e21"
      }
    },
    {
      "ref": "crm-1002",
      "status": "matched",
      "matchedBy": "orgNumber",
      "organization": {
        "id": "2b7e1c55-0d3a-4f7e-9c1b-8a6d5e4f3a21",
        "name": "Fjällräven Frakt AB",
        "detailsRevealed": false,
        "organizationNumber": "559012-3456",
        "countryCode": "SE",
        "city": "Stockholm",
        "legalForm": "Aktiebolag",
        "foundedYear": 2017,
        "url": "https://app.funnelfeedr.com/organizations/2b7e1c55-0d3a-4f7e-9c1b-8a6d5e4f3a21"
      }
    },
    {
      "ref": "crm-1003",
      "status": "not_found"
    }
  ],
  "creditsCharged": 0,
  "creditsQuoted": 0,
  "creditsRemaining": 412.4,
  "dryRun": false
}

A match returns the basics for free: name, country, city, legal form, founding year, the link to the organization in the app, and the identifier you matched by. The details — size, revenue, website, description, address and more — cost 0.2 credits per organization by default; add "reveal": ["details"] to reveal them in the same call (see Matching). An organization Funnelfeedr does not know is not_found, for free. (A field with no value is left out of the response, as in these examples; only nextCursor and creditsRemaining are sent as null.)

4. Match a person, as a dry run

Find a person by name at an organization and ask what revealing their email and phone would cost. dryRun: true spends nothing and needs no Idempotency-Key.

curl https://api.funnelfeedr.com/external/v1/people/match   -H "Authorization: Bearer $FUNNELFEEDR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "items": [
      { "ref": "lead-42", "name": "Anna Svensson", "organization": { "domain": "nordviklogistik.se" } }
    ],
    "reveal": ["email", "phone"],
    "dryRun": true
  }'

{
  "results": [
    {
      "ref": "lead-42",
      "status": "matched",
      "matchedBy": "name",
      "contact": {
        "id": "c0a8012e-5b1f-4e3d-9a7c-2f6b8d4e1a90",
        "name": "Anna Svensson-Berg",
        "jobTitle": "Head of Procurement",
        "isExecutive": false,
        "isDecisionMaker": true,
        "organizationId": "6f9d2f1e-6f37-4a2f-9a3e-1b5c0f4d7e21",
        "organizationName": "Nordvik Logistik AB",
        "email": "XXXXX@nordviklogistik.se",
        "emailIsMasked": true,
        "phone": "+46701XXXXXX",
        "phoneIsMasked": true,
        "linkedInUrl": "https://linkedin.com/in/anna-svensson-berg"
      },
      "reveal": {
        "creditCost": 1.2,
        "newInfoTypes": ["email", "phone"],
        "alreadyRevealedInfoTypes": [],
        "unavailableInfoTypes": []
      }
    }
  ],
  "creditsCharged": 0,
  "creditsQuoted": 1.2,
  "creditsRemaining": 412.4,
  "dryRun": true
}

Anna Svensson matched Anna Svensson-Berg: a hyphenated surname matches either half. The quote is exact: the real call charges creditsQuoted, or less if someone in your account revealed the same details in the meantime.

5. Reveal

Send the same request with dryRun: false, maxCredits set to the quote you accepted and a new Idempotency-Key. The key makes a retry safe: if the connection drops, send the identical request with the same key and you get the first answer back instead of a second charge.

curl https://api.funnelfeedr.com/external/v1/people/match   -H "Authorization: Bearer $FUNNELFEEDR_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: $(uuidgen)"   -d '{
    "items": [
      { "ref": "lead-42", "name": "Anna Svensson", "organization": { "domain": "nordviklogistik.se" } }
    ],
    "reveal": ["email", "phone"],
    "maxCredits": 1.2,
    "dryRun": false
  }'

{
  "results": [
    {
      "ref": "lead-42",
      "status": "matched",
      "matchedBy": "name",
      "contact": {
        "id": "c0a8012e-5b1f-4e3d-9a7c-2f6b8d4e1a90",
        "name": "Anna Svensson-Berg",
        "jobTitle": "Head of Procurement",
        "isExecutive": false,
        "isDecisionMaker": true,
        "organizationId": "6f9d2f1e-6f37-4a2f-9a3e-1b5c0f4d7e21",
        "organizationName": "Nordvik Logistik AB",
        "email": "anna.svensson-berg@nordviklogistik.se",
        "emailIsMasked": false,
        "phone": "+46701234567",
        "phoneIsMasked": false,
        "linkedInUrl": "https://linkedin.com/in/anna-svensson-berg"
      },
      "reveal": {
        "creditCost": 1.2,
        "newInfoTypes": ["email", "phone"],
        "alreadyRevealedInfoTypes": [],
        "unavailableInfoTypes": []
      }
    }
  ],
  "creditsCharged": 1.2,
  "creditsQuoted": 1.2,
  "creditsRemaining": 411.2,
  "dryRun": false
}

The revealed details stay revealed for your whole account for a year; asking for them again costs nothing. No uuidgen on Windows? In PowerShell use [guid]::NewGuid().

Tell your agent

If an AI agent — Claude Code, Cursor, Codex or your own — will call the API, paste this into the prompt you give it: its system prompt or instructions. It gives the agent the base URL, where the key is, the credit rules and where to read more on every run.

## Funnelfeedr API

- Base URL: https://api.funnelfeedr.com/external/v1
- Auth: `Authorization: Bearer $FUNNELFEEDR_API_KEY` (the key is in the environment; never print or commit it)
- Docs for agents: https://funnelfeedr.com/developers/llms.txt (everything in one file: https://funnelfeedr.com/developers/llms-full.txt)
- OpenAPI spec: https://funnelfeedr.com/developers/openapi.json
- Every lookup takes `items`, an array of 1-25 objects, and answers per item in the same order.

### Credit rules

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.

Next steps

Matching: every status organizations/match, organizations/switchboards/match and people/match can return, and how organizations/contacts/match picks contacts, with full examples.
Credits & reveal: what costs what and how the cap works.
Agent guidance: the rules behind the snippet above.
API reference: every endpoint and field.