Administrator Guide

Zapier API Documentation

This document describes the YouEx.ai API surface used by the YouEx.ai Zapier integration.

YouEx.ai Zapier API Documentation

Last updated: May 28, 2026

This document describes the YouEx.ai API surface used by the YouEx.ai Zapier integration. It is intended for integrators who need a clear reference for authentication, supported endpoints, request/response formats, and webhook payloads.

Access

Access our Zapier app here: YouEx.ai Public Invite

Overview

The YouEx.ai Zapier app integrates with the YouEx.ai CRM and webhook event system.

It supports:

User/account identification
Workspace discovery
CRM record create/read/update/delete for:
- Leads
- Contacts
- Companies (accounts)
- Opportunities
Polling and REST Hook triggers for CRM record events

Base URL

https://engage.youex.ai/api/zapier

Authentication

All Zapier API endpoints require an Auth0-issued bearer token.

Authorization header

Authorization: Bearer <access_token>

Authentication errors

`401 unauthorized`

Returned when the bearer token is missing or invalid.

Example:

{
  "error": "unauthorized",
  "error_description": "Missing or invalid Authorization header"
}

`401 invalid_token`

Returned when JWT verification fails.

{
  "error": "invalid_token",
  "error_description": "Token validation failed"
}

`403 insufficient_scope`

Returned when the token is valid but missing required scopes.

{
  "error": "insufficient_scope",
  "error_description": "Missing required scopes: crm:write"
}

Workspace model

Zapier operations run in the caller’s selected Zapier-enabled workspace.

Important behavior:

If the authenticated user has exactly one eligible workspace, that workspace is used automatically.
If the authenticated user has multiple eligible workspaces, they must choose an Integration Workspace in YouEx.ai profile settings before using the app.
If a record belongs to a different workspace than the selected Integration Workspace, the API returns a workspace mismatch error.

Workspace errors

Integration workspace required

{
  "error": "integration_workspace_required",
  "error_description": "User has multiple Zapier-enabled workspaces. Choose an Integration Workspace in Profile Settings before using Zapier."
}

Integration workspace mismatch

{
  "error": "integration_workspace_mismatch",
  "error_description": "The requested resource belongs to a different workspace than the selected Integration Workspace. Choose the matching Integration Workspace in Profile Settings before using Zapier."
}

Common conventions

Content type

Request and response bodies use JSON.

Content-Type: application/json

Error format

Most validation and runtime errors are returned as:

{
  "error": "Human-readable message"
}

Some authorization and workspace-selection errors return structured error and error_description fields as shown above.

Pagination

List endpoints support cursor pagination.

Common query parameters:

cursor - opaque cursor from a previous response
limit - integer, minimum 1, maximum 200
search - free-text search string

List endpoints may also return pagination data in headers:

x-total-count
x-has-more
x-next-cursor

Endpoints

1. Account and workspace endpoints

GET `/account`

Returns the authenticated Zapier user summary.

Required scope: none beyond a valid bearer token

Response

{
  "id": "auth0|abc123",
  "email": "user@example.com",
  "label": "user@example.com",
  "workspaceCount": 2
}

GET `/workspaces`

Returns the authenticated user’s Zapier-enabled workspaces.

Required scope: crm:read

Query parameters

email - optional email address; if supplied, it must match the authenticated user

Response

[
  {
    "id": "ws_123",
    "name": "Acme RevOps",
    "slug": "acme-revops",
    "workspaceShortId": "ACME01"
  }
]

2. CRM event feed endpoint

GET `/events/:entityType/:eventType`

Returns recent CRM events for polling-based Zapier triggers.

Required scope: crm:read

Path parameters

entityType - one of:
- lead
- contact
- company
- opportunity
eventType - one of:
- created
- updated
- deleted

Query parameters

since - optional ISO 8601 timestamp
limit - optional integer, default 50, max 200
watchedFields - optional array or comma-separated list of field names to filter update events

Response

[
  {
    "event_id": "evt_01",
    "workspaceId": "ws_123",
    "workspace_id": "ws_123",
    "record_id": "lead_01",
    "entity_type": "lead",
    "event_type": "updated",
    "occurred_at": "2026-05-28T15:30:00.000Z",
    "changed_fields": ["status", "title"],
    "record": {
      "_id": "lead_01",
      "name": "Avery Smith",
      "email": "avery@example.com",
      "status": "Hot"
    }
  }
]

3. Webhook subscription endpoints

YouEx.ai supports Zapier REST Hook subscriptions for CRM entity events.

3.1 Canonical subscription endpoint

POST `/subscriptions`

Creates a webhook subscription.

Required scope: crm:hooks

Request body

{
  "entityType": "lead",
  "eventType": "updated",
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc",
  "watchedFields": ["status", "email"]
}

Fields

entityType - lead, contact, company, or opportunity
eventType - created, updated, or deleted
targetUrl - Zapier target webhook URL
watchedFields - optional array of field names; when provided, updated-event webhooks only fire if one of those fields changed

Response

{
  "subscriptionId": "sub_123",
  "workspaceId": "ws_123",
  "entityType": "lead",
  "eventType": "updated",
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc",
  "watchedFields": ["status", "email"],
  "status": "active"
}

DELETE `/subscriptions/:subscriptionId`

Deletes a webhook subscription.

Required scope: crm:hooks

Response

{
  "id": "sub_123",
  "deleted": true
}

3.2 Zapier REST Hook compatibility endpoints

These endpoints exist to align with Zapier REST Hook subscription conventions.

Creates a webhook subscription using Zapier-style field names.

Required scope: crm:hooks

Request body

{
  "target_url": "https://hooks.zapier.com/hooks/catch/123/abc",
  "event": "updated_lead",
  "watched_fields": ["status", "email"]
}

hookUrl may be used instead of target_url.

Supported `event` values

new_lead
updated_lead
deleted_lead
new_contact
updated_contact
deleted_contact
new_company
updated_company
deleted_company
new_opportunity
updated_opportunity
deleted_opportunity

Response

{
  "id": "sub_123",
  "workspaceId": "ws_123",
  "event": "updated_lead",
  "target_url": "https://hooks.zapier.com/hooks/catch/123/abc",
  "status": "active"
}

DELETE `/unsubscribe/:subscriptionId`

Deletes a Zapier REST Hook subscription.

Required scope: crm:hooks

Response

{
  "id": "sub_123",
  "deleted": true
}

DELETE `/unsubscribe`

Deletes a Zapier REST Hook subscription when the subscription identifier is supplied via query string or request body.

Required scope: crm:hooks

YouEx.ai accepts:

subscriptionId
hookUrl

Example

DELETE /api/zapier/unsubscribe?subscriptionId=sub_123

Response

{
  "id": "sub_123",
  "deleted": true
}

4. CRM object APIs

YouEx.ai exposes CRUD endpoints for four CRM object types:

Lead
Contact
Account
Opportunity

Record IDs

All record detail, update, and delete endpoints use :recordId in the path.

Workspace validation

All CRM actions are workspace-scoped. Related object references are validated to ensure they belong to the same workspace.

4.1 Lead API

POST `/crm/lead`

Creates a lead.

Required scope: crm:write

Request body

{
  "name": "Avery Smith",
  "email": "avery@example.com",
  "phone": "+1-555-0100",
  "company": "Acme",
  "companyWebsite": "https://acme.example",
  "title": "VP Revenue",
  "status": "New",
  "notes": "Captured from partner workflow",
  "tags": ["zapier", "inbound"]
}

Supported fields

name - required
email
secondaryEmail
phone
secondaryPhone
linkedinUrl
company
companyWebsite
title
status - one of New, VIP, Hot, Warm, Medium, Cold, Opportunity
notes
tags - array of strings
contactId
companyId
opportunityId

cursor
limit
search
status

{
  "id": "lead_01",
  "deleted": true
}

{
  "name": "Avery Smith",
  "email": "avery@example.com",
  "phone": "+1-555-0100",
  "companyId": "company_01",
  "companyName": "Acme",
  "title": "VP Revenue",
  "status": "Active",
  "tags": ["customer"]
}

Supported fields

name - required
email
secondaryEmail
phone
secondaryPhone
linkedinUrl
sourceLeadId
sourceConversationId
companyId
companyName
title
notes
tags
status - one of Active, Inactive, Do Not Contact

GET `/crm/contacts`

Returns a paginated list of contacts.

Required scope: crm:read

Query parameters

cursor
limit
search
status
companyId

Response

{
  "records": [],
  "total": 0,
  "hasMore": false,
  "nextCursor": null
}

{
  "name": "Acme",
  "industry": "SaaS",
  "website": "https://acme.example",
  "type": "Customer",
  "status": "Prospect",
  "city": "Chicago",
  "state": "IL",
  "country": "US",
  "tags": ["target"]
}

Supported fields

name - required
industry
website
sourceLeadId
type - one of Customer, Competitor, Vendor, Partner, Other
primaryContactId
streetAddress1
streetAddress2
city
state
country
notes
tags
status - one of Active, Inactive, Prospect, Former

GET `/crm/accounts`

Returns a paginated list of accounts.

Required scope: crm:read

Query parameters

cursor
limit
search
type

Response

{
  "records": [],
  "total": 0,
  "hasMore": false,
  "nextCursor": null
}

GET `/crm/account/:recordId`

Returns a single account.

Required scope: crm:read

PATCH `/crm/account/:recordId`

Updates an account.

Required scope: crm:write

Notes:

workspaceId is ignored if included in the patch payload.

{
  "name": "Acme Expansion",
  "companyId": "company_01",
  "companyName": "Acme",
  "contactId": "contact_01",
  "contactName": "Avery Smith",
  "amount": 25000,
  "probability": 40,
  "stage": "Qualification",
  "closeDate": "2026-06-30",
  "notes": "Expansion deal",
  "tags": ["pipeline"]
}

Supported fields

name - required
sourceLeadId
sourceConversationId
companyId
companyName
contactId
contactName
amount
probability - number from 0 to 100
stage - one of:
- Prospecting
- Qualification
- Needs Analysis
- Proposal
- Negotiation
- Closed Won
- Closed Lost
closeDate
notes
tags

GET `/crm/opportunities`

Returns a paginated list of opportunities.

Required scope: crm:read

Query parameters

cursor
limit
search
stage

Response

{
  "records": [],
  "total": 0,
  "hasMore": false,
  "nextCursor": null
}

GET `/crm/opportunity/:recordId`

Returns a single opportunity.

Required scope: crm:read

PATCH `/crm/opportunity/:recordId`

Updates an opportunity.

Required scope: crm:write

Notes:

workspaceId is ignored if included in the patch payload.

Content-Type: application/json

Delivery body

{
  "event_id": "evt_01",
  "workspaceId": "ws_123",
  "workspace_id": "ws_123",
  "record_id": "lead_01",
  "entity_type": "lead",
  "event_type": "updated",
  "occurred_at": "2026-05-28T15:30:00.000Z",
  "changed_fields": ["status", "email"],
  "record": {
    "_id": "lead_01",
    "name": "Avery Smith",
    "email": "avery@example.com",
    "status": "Hot"
  }
}

Webhook behavior notes

For created and deleted events, subscriptions fire whenever the matching entity event occurs.
For updated events:
- if watchedFields is empty or omitted, all updates match
- if watchedFields is provided, the webhook fires only if at least one watched field changed

Retry behavior

If a webhook delivery fails:

YouEx.ai retries failed deliveries with backoff.
If the destination repeatedly responds with 404 or 410, the subscription may be disabled automatically after repeated failures.

Validation rules

YouEx.ai validates cross-record references within the selected workspace.

Examples:

A lead contactId must reference a contact in the same workspace.
A contact companyId must reference a company in the same workspace.
An opportunity companyId, contactId, sourceLeadId, and sourceConversationId must reference records in the same workspace.

If validation fails, the API returns 400.

Example:

{
  "error": "companyId must reference a company in this workspace"
}

HTTP status codes

Common status codes returned by the Zapier API:

200 OK - successful read, update, or delete
201 Created - successful create
400 Bad Request - invalid payload, invalid parameters, or missing Integration Workspace
401 Unauthorized - missing or invalid token
403 Forbidden - insufficient scope, feature access denied, or workspace mismatch
404 Not Found - record or subscription not found
402 Payment Required - workspace subscription inactive
500 Internal Server Error - unexpected server error

Feature gating

Zapier API access is only available for workspaces with the zapierIntegration feature enabled.

If Zapier is not enabled for the selected workspace, the API may return:

{
  "error": "Feature zapierIntegration is not enabled for this workspace tier",
  "code": "feature_not_enabled",
  "details": {
    "feature": "zapierIntegration"
  }
}

Agent Configuration

Configure web agents, Q&A pairs, info fields, offers, and embed settings in YouEx.ai.

Knowledge Management

Build and maintain knowledge bases, files, and web pages for YouEx.ai agents.