YouEx.ai Zapier API Documentation

Last updated: 3 November 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.

The current contract is the API reference (PDF). Zapier is included on Professional and Enterprise (zapierIntegration). For CRM, email, research, and engagement from your own application, use the REST API.

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 access token issued for the Zapier audience.

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 from 1 to 200, default 50
• search - free-text search string
• dateFrom and dateTo - ISO-8601 timestamps with an offset
• dateField - createdAt or updatedAt

dateFrom must be earlier than or equal to dateTo. A later page must keep the same dateField as the cursor.

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, or null. On updates, an empty, null, or omitted watch list matches every change. A non-empty list fires only when 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.

POST /subscribe

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. The default event is new_lead.

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 - on create, one of New, VIP, Hot, Warm, Cold, Opportunity. Reads can also return Converted and Lost.
• notes
• tags - array of strings
• contactId
• companyId
• opportunityId

Response

Returns the created lead record. Created leads are stored with source API.

GET /crm/leads

Returns a paginated list of leads.

Required scope: crm:read

Query parameters

• cursor
• limit
• search
• status

Response

Returns an array of lead records.

GET /crm/lead/:recordId

Returns a single lead record.

Required scope: crm:read

PATCH /crm/lead/:recordId

Updates a lead.

Required scope: crm:write

Request body

Any subset of lead fields supported by the create endpoint.

DELETE /crm/lead/:recordId

Deletes a lead.

Required scope: crm:write

Response

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

4.2 Contact API

POST /crm/contact

Creates a contact.

Required scope: crm:write

Request body

{
  "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
}

GET /crm/contact/:recordId

Returns a single contact.

Required scope: crm:read

PATCH /crm/contact/:recordId

Updates a contact.

Required scope: crm:write

DELETE /crm/contact/:recordId

Deletes a contact.

Required scope: crm:write

4.3 Account API

In the Zapier API, an "account" maps to a company record in YouEx.ai.

POST /crm/account

Creates an account.

Required scope: crm:write

Request body

{
  "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

Unknown keys are rejected. workspaceId is not a client field.

DELETE /crm/account/:recordId

Deletes an account.

Required scope: crm:write

4.4 Opportunity API

POST /crm/opportunity

Creates an opportunity.

Required scope: crm:write

Request body

{
  "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
• closePlan
• closingNotes
• tags

Unknown keys are rejected. workspaceId is not a client field.

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

Send any subset of the create fields. Unknown keys are rejected. workspaceId is not a client field.

DELETE /crm/opportunity/:recordId

Deletes an opportunity.

Required scope: crm:write

Webhook delivery format

When a subscription is active, YouEx.ai sends a JSON POST request to the subscribed targetUrl.

Delivery headers

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, null, or omitted, all updates match
  • if watchedFields is non-empty, 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 - read, update, or delete succeeded
• 201 - create succeeded
• 400 - invalid payload, invalid cursor, or invalid date window
• 401 - missing or invalid token
• 403 - missing scope, Zapier is not on the plan, or workspace mismatch
• 404 - record or subscription was not found

Plan

Zapier is included on Professional and Enterprise (zapierIntegration). A workspace without it receives 403.