# 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

1. Make sure the API is enabled for your account. If **Settings → API keys** in [the app](https://app.funnelfeedr.com) shows a request-access screen, request it there; we enable it per account.
2. 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.
3. Copy the key. It is shown once; Funnelfeedr stores only a hash of it.
4. Put it in an environment variable on the machine that will call the API:

```bash
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](https://funnelfeedr.com/developers/authentication.md).

## 2. Make your first call

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

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

```json
{
  "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](https://funnelfeedr.com/developers/errors.md).

## 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.

```bash
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" }
    ]
  }'
```

```json
{
  "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](https://funnelfeedr.com/developers/matching.md#basics-and-details)). 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`.

```bash
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
  }'
```

```json
{
  "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.

```bash
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
  }'
```

```json
{
  "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.

```markdown
## 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](https://funnelfeedr.com/developers/matching.md): every status `organizations/match`, `organizations/switchboards/match` and `people/match` can return, and how `organizations/contacts/match` picks contacts, with full examples.
- [Credits & reveal](https://funnelfeedr.com/developers/credits-and-reveal.md): what costs what and how the cap works.
- [Agent guidance](https://funnelfeedr.com/developers/agent-guidance.md): the rules behind the snippet above.
- [API reference](https://funnelfeedr.com/developers/api-reference.md): every endpoint and field.