Using the API

Events

How POST /events records what happened in your own system on an organization's and a person's timeline — the fields, dedupe on your externalId, events that wait for an organization, the person-to-contact rules, and the optional follow-up task and feed card.

POST /external/v1/events tells Funnelfeedr that something happened in your own system — a signup, a created account, a trial that ran out — so sales see it on the organization's and the person's timeline. It is free, never spends credits, and counts against the write rate limit bucket of 10 requests a minute. Like every endpoint it takes 1–25 items and answers each one, in order, with your ref echoed (see Batching).

statusMeaning
createdThe event is stored. organizationMatched says whether it is on an organization; organizationId, contactId and taskId name where it landed and the follow-up it created.
duplicateAn event with this externalId was stored before. The ids are the stored event's; nothing was changed, and no follow-up or feed card was created again.
invalidThe item is unusable; error says why. The rest of the batch still runs.

Fields

FieldRule
externalIdRequired. Your id for the event, at most 200 characters, unique within your account and case-sensitive (Evt-1 and evt-1 are two events).
typeRequired. What happened, as a slug of a-z, 0-9, _, . and -, at most 64 characters: signed_up, trial_out_of_credits. There is no fixed list.
titleRequired. The line shown on the timeline, at most 200 characters.
descriptionOptional detail under the title, at most 2,000 characters.
urlOptional absolute https:// link back to the record in your system.
occurredAtWhen it happened, ISO 8601 with an offset. Defaults to now; may not be in the future.
sourceThe name of your system, shown as the actor, at most 100 characters.
propertiesA flat map of strings shown with the event: at most 20 entries, keys up to 64 characters, values up to 500.
organizationThe identifiers of organizations/match: id, orgNumber (with countryCode), linkedInUrl or domain, tried in that order.
personemail, name, phone, jobTitle.
followUpOptional task: note, dueAt (default today), assignedUserId or assignedTeamId.
feedtrue to post the event to the account's feed as well. Default false.

Every item needs person.email or an organization identifier, or it is invalid with missing_identifier. A required field that is absent or blank is missing_field; a value that is there but unusable (a url that is not https, an occurredAt in the future, an assignedUserId who is not in your account) is invalid_value.

Dedupe on externalId

Give every event a deterministic externalId, such as account-created:4711. Sending it again — a retry after a timeout, a job that runs twice — answers duplicate with the event stored the first time, whatever the rest of the item says. So you never need an Idempotency-Key here, and never get two events for one thing that happened.

Events that wait for an organization

An organization that matches nothing does not fail the item. The event is stored with organizationMatched: false and is on no timeline yet. When a later event with the same person.email names an organization that matches, the earlier events move there too. So send "signed up" with just the email, and "account created" with the email and the organization: both end up on the organization. Funnelfeedr never creates an organization from an event.

The person

With a matched organization the person becomes a contact there:

  1. an email your account already owns or has revealed finds that contact;
  2. otherwise the name is matched among the organization's contacts (exactly, after folding case and accents; several matches place nobody);
  3. otherwise a new contact, visible only to your account, is created.

The email and phone you send are added to the contact as your account's own; nothing is revealed or charged. Nothing is pushed to your CRM. A person on the privacy suppression list is not stored at all; the event stays on the organization without them. Without an organization no contact is created: the person's details wait on the event.

Follow-up and feed

  • followUp creates a task on the organization and the contact, with the event's title as its subject and taskId on the result. It goes to assignedUserId, else a member of assignedTeamId (the organization's owner when in the team, else the member with the fewest open tasks), else the organization's owner, else nobody. An event without an organization gets no task, and none is created when it moves to one later.
  • feed: true posts one card to the account's feed. An event without an organization gets its card too, without the organization.

Neither runs again on a duplicate.

Example

curl https://api.funnelfeedr.com/external/v1/events \
  -H "Authorization: Bearer $FUNNELFEEDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "ref": "account-4711",
        "externalId": "account-created:4711",
        "type": "account_created",
        "title": "Created an account",
        "description": "Chose the Team plan during the trial.",
        "url": "https://admin.nordvik.example/accounts/4711",
        "occurredAt": "2026-11-10T09:21:00+00:00",
        "source": "Nordvik app",
        "properties": { "plan": "team", "seats": "5" },
        "organization": { "domain": "nordviklogistik.se" },
        "person": {
          "email": "anna.svensson@nordviklogistik.se",
          "name": "Anna Svensson",
          "phone": "+46 70 123 45 67",
          "jobTitle": "Head of Procurement"
        },
        "feed": true
      }
    ]
  }'
{
  "results": [
    {
      "ref": "account-4711",
      "status": "created",
      "eventId": "1f7a3e95-c2d4-4b6e-8a90-5d3c7b1e2f48",
      "organizationMatched": true,
      "organizationId": "6f9d2f1e-6f37-4a2f-9a3e-1b5c0f4d7e21",
      "contactId": "c0a8012e-5b1f-4e3d-9a7c-2f6b8d4e1a90"
    }
  ]
}

A signup known only by its email is stored and waits:

{
  "results": [
    {
      "ref": "signup-8812",
      "status": "created",
      "eventId": "9b2f6c1d-4e8a-4f3b-a7d5-2c1e0f9b8a64",
      "organizationMatched": false
    }
  ]
}

The API reference has every field and the duplicate and invalid examples.