Record an event
Tell Pedibee something a person did in your product, so automations can start, wait or stop.
/api/v1/eventsevents:writeRecords one event about one person — they signed up, started a trial, a payment failed — and runs automations on it straight away:
- Live automations that start on this event start for that person.
- Automations waiting for it (wait for an event) carry on.
- Runs that end on it (exit rules and goals) stop.
The answer says what happened, so you can see at once whether your event did anything.
Send the person by email, by your own externalId (your user id), or by Pedibee contact id. An email we don't know becomes a new contact (unless you send createContact: false). Your externalId is saved on the contact, so later events can send it alone.
Body
Prop
Type
Late events
Events that happened more than 72 hours before they arrive (7 days for transactional automations) are recorded but don't start anything, so a backfill never emails people about last month. They still end runs and reach goals.
Property names like password, card_number or ssn are refused: keep secrets out of event data. Names starting with pedibee. are reserved for events Pedibee records itself.
Example request
curl -X POST "https://api.pedibee.com/api/v1/events" \
-H "Authorization: Bearer $PEDIBEE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "user_signed_up",
"id": "signup_8841",
"contact": { "email": "jane@northwind.io", "externalId": "u_8841" },
"properties": { "plan": "pro", "trial_ends_at": "2026-11-01" },
"contactFields": { "name": "Jane Doe" }
}'Response
{
"id": "6703f1c2a9e4b0a1b2c3d4e5",
"name": "user_signed_up",
"contactId": "66f1c2a9e4b0a1b2c3d4e5f6",
"duplicate": false,
"outcome": "PROCESSED",
"createdContact": true,
"runsStarted": 1,
"runsExited": 0,
"runsResumed": 0,
"runsConverted": 0,
"note": null
}outcome is PROCESSED, NO_CONTACT (nobody matched and creating was off) or TOO_OLD. A repeated id answers with the first event and duplicate: true. note explains when nothing started (for example, the person is already in a run of that automation).
Limits
The key's usual limits (100 requests per 10 seconds, 50,000 a day), and 50 events a second and 100,000 a day per workspace. Over a limit you get 429 with Retry-After.
Errors
| Status | When |
|---|---|
400 | name or contact is missing or invalid, properties are too big or contain a secret, occurredAt is in the future. |
403 | The key doesn't have events:write, or the request came from a browser. |
404 | contact.id isn't in your workspace. |
409 | email and externalId belong to two different contacts. |
401 | The API key is missing, invalid, revoked or expired. |
429 | Too many events. Wait for the seconds in Retry-After. |