# 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](https://funnelfeedr.com/developers/rate-limits.md) 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](https://funnelfeedr.com/developers/batching.md)).

| `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:

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

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

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

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

The [API reference](https://funnelfeedr.com/developers/api-reference.md) has every field and the `duplicate` and `invalid` examples.
