Funnelfeedr Logo

Using the API

Batching

Every lookup and reveal takes an array of 1 to 25 items and answers each one separately, in order, with your ref echoed back.

There are no single-item endpoints. Matching, contacts, switchboards and reveals all take items, an array of 1 to 25 objects, and return one result per item in results. One item is just a batch of one.

{
  "items": [
    { "ref": "crm-2001", "linkedInUrl": "https://www.linkedin.com/in/nordvik" },
    { "ref": "crm-2002", "domain": "nordviklogistik.se" }
  ]
}

{
  "results": [
    {
      "ref": "crm-2001",
      "status": "invalid",
      "error": {
        "code": "invalid_value",
        "message": "linkedInUrl must be an organization's LinkedIn page, https://www.linkedin.com/company/…"
      }
    },
    {
      "ref": "crm-2002",
      "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"
      }
    }
  ],
  "creditsCharged": 0,
  "creditsQuoted": 0,
  "creditsRemaining": 412.4,
  "dryRun": false
}

The rules

  • 1 to 25 items. An empty or missing array fails the whole request with 422 validation_failed; more than 25 with 422 too_many_items (the body carries maxItems: 25). Split larger jobs into several requests.
  • Same order. results[i] answers items[i], always.
  • ref is yours. Optional, at most 200 characters — a CRM id, a row number. It comes back unchanged so you never have to rely on order alone. Funnelfeedr does not store it.
  • A status per item. Each result has a status. A bad item gets "status": "invalid" with an error, and the rest of the batch still runs. A 200 response therefore does not mean every item worked: check each status.
  • Malformed JSON fails the whole request. A value of the wrong type — an id that is not a UUID, say — is caught before any item runs: 422 validation_failed, with the field path in errors ("items[3].organization.id": ["Must be a UUID."]).
  • One request, one charge. A batch that reveals is quoted, capped and charged as a whole. See Credits & reveal.

Item errors

An invalid item's error has a stable code and a human-readable message naming the field to fix:

codeMeaning
missing_identifierThe item names nothing to look up. An empty or blank field counts as not sent.
invalid_valueA field is present but unusable: an email without @, a LinkedIn URL of the wrong kind, a name with no letters in it, a ref over 200 characters.
missing_organizationpeople/match: a name was given without an organization.
missing_idNo id on a reveal item.
invalid_cursororganizations/contacts/match: a cursor that was altered, or that belongs to another organization than the item's identifiers name.

Fix the item and send it again on its own or in your next batch; the other items already have their answers.

Large jobs

For a CRM of 10,000 organizations, send 400 requests of 25. They count against your rate limits like any other request, so pace them: the matching endpoints, organizations' contacts included, share the search bucket of 20 requests a minute by default, which at 25 items per request is 500 items a minute. Honour Retry-After if you get a 429.

There are no asynchronous bulk jobs, file uploads or webhooks in v1. Every request answers synchronously.