API Reference

REST endpoints for sending events, bulk imports, and CSV uploads.

Authentication

All requests require a Bearer token in the Authorization header. Create API keys in your dashboard. Keys start with zo_live_.

Authorization: Bearer zo_live_your_api_key

Base URL

https://api.zoody.io

Rate limits

API requests are limited to 120 requests per minute per IP. Monthly event limits depend on your plan:

Plan	Events / month
Free	1,000
Pro	50,000
Growth	500,000

POST

/v1/events

Send up to 100 events per request. Events are processed asynchronously and synced to HubSpot based on your mapping configuration.

Request

curl -X POST https://api.zoody.io/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zo_live_your_api_key" \
  -d '{
    "events": [
      {
        "eventName": "feature_used",
        "email": "user@example.com",
        "timestamp": "2026-03-12T10:30:00Z",
        "properties": {
          "feature": "dashboard",
          "duration_seconds": 120
        }
      }
    ]
  }'

Response (202 Accepted)

{
  "accepted": 1,
  "rejected": 0,
  "requestId": "req_abc123",
  "eventIds": ["evt_def456"]
}

Event fields

Field	Type	Required	Description
eventName	string	Yes	Max 255 characters
email	string	*	Contact matching
domain	string	*	Company matching
timestamp	string	No	ISO 8601 (defaults to now)
eventId	string	No	For deduplication (auto-generated)
properties	object	No	Max 50 keys

* At least one of email or domain is required.

Error responses

Status	Meaning
400	Validation error (check the errors array)
401	Invalid or revoked API key
402	Monthly event limit exceeded
429	Rate limit exceeded (120 req/min)

POST

/v1/events/bulk

Send up to 10,000 events for historical backfill. Events are queued as a background job and processed in 500-event chunks.

Request

curl -X POST https://api.zoody.io/v1/events/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zo_live_your_api_key" \
  -d '{
    "events": [
      {
        "eventName": "feature_used",
        "email": "user1@example.com",
        "timestamp": "2026-01-15T08:00:00Z",
        "properties": { "feature": "reports" }
      },
      {
        "eventName": "feature_used",
        "email": "user2@example.com",
        "timestamp": "2026-01-15T09:30:00Z",
        "properties": { "feature": "dashboard" }
      }
    ]
  }'

Response (202 Accepted)

{
  "jobId": "job_abc123",
  "totalEvents": 2,
  "status": "queued"
}

POST

/v1/backfill/csv

Upload a CSV file of historical events. Max 50 MB, up to 10,000 rows.

Request

curl -X POST https://api.zoody.io/v1/backfill/csv \
  -H "Authorization: Bearer zo_live_your_api_key" \
  -F "file=@events.csv"

CSV format

Required columns: event_name, timestamp, and at least one of email or domain. All other columns become event properties.

event_name,email,timestamp,feature,plan
feature_used,user1@example.com,2026-01-15T08:00:00Z,reports,pro
feature_used,user2@example.com,2026-01-15T09:30:00Z,dashboard,free
login,user1@example.com,2026-01-16T10:00:00Z,,pro