Skip to content
Pidgely Docs

API reference · Events

Record an event

POSThttps://api.pidgely.com/events
View as Markdown

Records something a contact did in your product and creates or updates the contact (names and properties; consent never changes). Events start organization automations with the event trigger, end them through goals and exit events, resume wait-for-event steps and feed the inactivity trigger. Every plan; full_access and sending_access keys. See Events.

Records an event of a contact (user_signed_up, trial_started, payment_failed...) and creates or updates the contact. Events start organization automations (event trigger), end them (goals and exit events), resume wait-for-event steps and feed the inactivity trigger. Full access and sending access keys, every plan. With idempotency_key (or the Idempotency-Key header), a repeated event within 30 days is not recorded again (duplicate: true). Events older than 24 hours are recorded and update the contact's last activity but start no automation.

Authorization: Bearer pdg_…. Any API key (full_access or sending_access).

Body parameters

JSON object.

Name Type Required Description
name string Yes Display name. Pattern: ^[A-Za-z0-9_.:-]{1,100}$.
email string Yes Email address.
contact object No Creates or updates the contact (names and properties; consent is never changed by events).
contact.first_name string No First name, up to 200 characters. Available as {{{FIRST_NAME}}} in broadcasts.
contact.last_name string No Last name, up to 200 characters. Available as {{{LAST_NAME}}} in broadcasts.
contact.properties object (map of any) No Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.
properties object (map of any) No Flat JSON object (strings, numbers, booleans), up to 50 keys and 16 KB. Available in e-mails as {{{event.<key>}}}.
occurred_at string No When it happened (default now; at most 5 minutes in the future). Format: date-time.
idempotency_key string No Up to 256 characters.

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL
curl -X POST 'https://api.pidgely.com/events' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "trial_started",
  "email": "ana.souza@example.com",
  "contact": {
    "first_name": "Ana",
    "last_name": "Souza",
    "properties": {
      "plan": "pro",
      "trial_ends_at": "2026-11-05"
    }
  },
  "properties": {
    "plan": "pro",
    "trial_days": 14
  },
  "idempotency_key": "trial-started-8812"
}'

Response

200 OK

JSON
{
  "object": "event",
  "id": "0199e4a2-7b8c-7d9e-8f0a-1b2c3d4e5f61",
  "name": "trial_started",
  "email": "ana.souza@example.com",
  "contact_id": "0199d7f4-5d7b-7a2c-b4e1-9f3c2a6d8e05",
  "properties": {
    "plan": "pro",
    "trial_days": 14
  },
  "occurred_at": "2026-10-22T12:00:00Z",
  "received_at": "2026-10-22T12:00:00.184Z",
  "duplicate": false
}

Response fields

Name Type Required Description
object string Yes Object type. One of event.
id string Yes Unique id (UUID). UUID.
name string Yes Display name.
email string Yes Email address.
contact_id string | null Yes UUID.
properties object (map of any) Yes Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.
occurred_at string Yes Format: date-time.
received_at string Yes Format: date-time.
duplicate boolean Yes The idempotency key was already used (the original event is returned).

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.
422 validation_error Invalid name or email, too many or nested properties, or occurred_at more than 5 minutes in the future (field names it).