Zapier API

Authentication

ZoeRelay uses OAuth 2.0 Authorization Code flow. Access and refresh credentials are opaque, confidential and must never be placed in Zap fields or URLs. API calls use Authorization: Bearer <access_token>.

Token exchange supports authorization_code; refresh uses refresh_token with rotation. Revocation invalidates the connection and disables its REST Hook subscriptions.

Scopes

contacts:read, contacts:write, conversations:read, conversations:write, tickets:read, tickets:write, automation:read, automation:write, and profile:read.

Contacts

Find Contact by contact_id, normalized email, or phone. Results are bounded and ordered by recent updates.

Create Contact requires an email or phone. Duplicate normalized emails return a conflict instead of silently merging records.

Update Contact can change name, email, and phone. The Zapier search is paired with Create Contact to support Find or Create Contact.

Tickets

Find by ticket ID or contact email. Create and update the supported subject, description, priority and status fields.

Conversations and messages

Find by ID, contact email, or external reference. Actions create a conversation, send a customer-visible message, add an internal note, assign an operator, change status, or request human handoff.

Tags

Find Tag uses the bounded tag helper. Add Tag and Remove Tag currently support conversation resources.

Users, teams, inboxes and dropdowns

Read-only helper endpoints return at most 100 workspace-scoped options for users, teams, inboxes, tags, automations, contacts, tickets and conversations:

GET /api/zapier/v1/meta/users
GET /api/zapier/v1/meta/teams
GET /api/zapier/v1/meta/inboxes
GET /api/zapier/v1/meta/tags
GET /api/zapier/v1/meta/automations
GET /api/zapier/v1/meta/contacts
GET /api/zapier/v1/meta/tickets
GET /api/zapier/v1/meta/conversations

These endpoints power human-readable dynamic dropdowns and hidden Find User, Find Tag, Find Inbox and Find Automation searches.

Automations

Only active, published manual workflows explicitly configured with allowZapierInvocation=true are listed and can be run. Execution also requires the connected operator’s current workflow permission.

REST Hooks

Subscriptions are connection-bound and duplicate-safe. Target URLs are encrypted. Event envelopes contain a unique top-level id, event_type, ISO 8601 UTC occurred_at, and event-specific fields.

{
  "id": "zevt_…",
  "event_type": "contact.created",
  "occurred_at": "2026-08-12T12:00:00.000Z",
  "contact_id": "…"
}

Delivery is asynchronous and durable. HTTP 410 disables a subscription. HTTP 408, 429, retryable 5xx responses, timeouts and transient network failures use bounded retries; numeric Retry-After is honored within the retry ceiling. Exhausted deliveries enter a reviewable dead-letter state.

Errors

• 400 invalid or incomplete input.
• 401 missing, expired or revoked OAuth credential.
• 403 missing OAuth scope or current workspace permission.
• 404 resource not found within the connected workspace.
• 409 duplicate resource, idempotency conflict or active replay.
• 422 semantically invalid input where applicable.
• 429 rate limit exceeded.
• 5xx transient service failure; retry with backoff.

Error responses expose safe codes and messages, not credentials or cross-workspace resource existence.

Rate limits and idempotency

The Zapier façade currently allows 300 requests per 60-second window for an authenticated rate-limit identity. Response headers expose the effective limit, remaining requests and reset time. The policy is Redis-backed and fails closed if distributed enforcement is unavailable.

Mutation actions use a stable idempotency key scoped to the OAuth connection and operation. Replaying the same key and payload returns the durable result; reusing a key with different input returns a conflict. Records are retained for 30 days.

Security and isolation

Every API request derives its workspace from the verified OAuth token. Request payloads cannot select another tenant. ZoeRelay then evaluates both the granted OAuth scope and the operator’s current workspace RBAC permission. Resource queries remain workspace-scoped and return no cross-tenant details.