Skip to content
Pidgely Docs

API reference · Events

Record events in a batch

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

Up to 100 events in one request, each handled like Record an event. Invalid events are reported in errors by index; the others are recorded.

Up to 100 events, each recorded like POST /events. Invalid events are reported by index and the others are recorded.

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

Body parameters

JSON object.

Name Type Required Description
events object[] Yes Event types to subscribe to, for example email.delivered. See Webhooks.
events[].name string Yes Display name. Pattern: ^[A-Za-z0-9_.:-]{1,100}$.
events[].email string Yes Email address.
events[].contact object No Creates or updates the contact (names and properties; consent is never changed by events).
events[].contact.first_name string No First name, up to 200 characters. Available as {{{FIRST_NAME}}} in broadcasts.
events[].contact.last_name string No Last name, up to 200 characters. Available as {{{LAST_NAME}}} in broadcasts.
events[].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.
events[].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>}}}.
events[].occurred_at string No When it happened (default now; at most 5 minutes in the future). Format: date-time.
events[].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/batch' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "events": [
    {
      "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"
    },
    {
      "name": "login",
      "email": "bruno@example.com"
    }
  ]
}'

Response

200 OK

JSON
{
  "data": [
    {
      "index": 0,
      "id": "0199e4a2-7b8c-7d9e-8f0a-1b2c3d4e5f61",
      "duplicate": false
    }
  ],
  "errors": [
    {
      "index": 1,
      "message": "email: missing @"
    }
  ]
}

Response fields

Name Type Required Description
data object[] Yes Items of this page.
data[].index integer Yes —
data[].id string Yes Unique id (UUID). UUID.
data[].duplicate boolean Yes —
errors object[] Yes —
errors[].index integer Yes —
errors[].message string Yes —

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.