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).
status | Meaning |
|---|---|
created | The 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. |
duplicate | An 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. |
invalid | The item is unusable; error says why. The rest of the batch still runs. |
Fields
| Field | Rule |
|---|---|
externalId | Required. Your id for the event, at most 200 characters, unique within your account and case-sensitive (Evt-1 and evt-1 are two events). |
type | Required. 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. |
title | Required. The line shown on the timeline, at most 200 characters. |
description | Optional detail under the title, at most 2,000 characters. |
url | Optional absolute https:// link back to the record in your system. |
occurredAt | When it happened, ISO 8601 with an offset. Defaults to now; may not be in the future. |
source | The name of your system, shown as the actor, at most 100 characters. |
properties | A flat map of strings shown with the event: at most 20 entries, keys up to 64 characters, values up to 500. |
organization | The identifiers of organizations/match: id, orgNumber (with countryCode), linkedInUrl or domain, tried in that order. |
person | email, name, phone, jobTitle. |
followUp | Optional task: note, dueAt (default today), assignedUserId or assignedTeamId. |
feed | true 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:
- an email your account already owns or has revealed finds that contact;
- otherwise the name is matched among the organization's contacts (exactly, after folding case and accents; several matches place nobody);
- 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
followUpcreates a task on the organization and the contact, with the event'stitleas its subject andtaskIdon the result. It goes toassignedUserId, else a member ofassignedTeamId(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: trueposts 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.