REST API

Last updated: 3 November 2026

Use this API from your own application. It performs the same CRM operations as MCP, except the three assistant widgets. Those widgets are not REST resources.

The current contract for this API, Zapier, Salesforce API v2, and MCP is the API reference (PDF).

YouEx.ai does not publish a general-purpose API key. A caller authenticates as one product. In-app session APIs are internal and are not part of this contract.

The REST API is included on Professional and Enterprise (restApi).

Base URL

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

Paths below are relative to that base.

Which API to use

A token never grants access to every workspace the user belongs to.

Authentication

Send:

Authorization: Bearer <access_token>
Content-Type: application/json
X-YouEx-Workspace-Id: <workspace-id>

The token is an Auth0 access token from Authorization Code with PKCE. The audience is https://engage.youex.ai/api/v1.

These tokens are rejected:

• a website, MCP, Zapier, or Salesforce token
• a client-credentials token
• a cookie session

Owners and Admins of a workspace with API access see the client ID, authorize URL, and token URL under Workspace Settings → Integrations. The authorize request uses scope=openid email profile crm:read crm:write, plus a PKCE code_challenge. YouEx registers the application's redirect URL.

crm:write does not include crm:read. Request both when the application does both.

Workspace

Send X-YouEx-Workspace-Id for a workspace the user belongs to.

• If the header is omitted and the user has exactly one workspace with API access, that workspace is used.
• If the user has more than one, the API returns workspace_selection_required and the eligible workspace ids and names.

Profile → Integration Workspace is not used. That setting is for MCP and Zapier.

{
  "error": "workspace_selection_required",
  "error_description": "Send the X-YouEx-Workspace-Id header. This user belongs to more than one workspace with API access.",
  "workspaces": [{ "id": "ws_123", "name": "Acme" }]
}

Limits and errors

300 authenticated requests per user per 15 minutes. Over the limit, the API returns 429.

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

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

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

Conventions

• Ids travel in the path. Filters travel in the query. Creates and updates are JSON bodies.
• A path id overrides the same field in the body.
• List filters match the MCP operation for that path, including cursor, limit, searchTerm, status, tag, and timeframe where that operation publishes them.
• When a list has more rows, send the returned cursor back as cursor.
• A successful call returns that operation's JSON object.
• GET of one lead, contact, company, or opportunity returns { "lead": {} } (or contact, company, opportunity).
• Created leads are stored with source MCP Tool, because these routes use the same operations as MCP.
• Engagement reads omit IP address, precise location, and raw user agent.
• Research text is omitted from list and search results.
• Opportunities have no research report.

Shared CRM values

These values are the same on every surface that writes CRM records.

companyId, contactId, opportunityId, and sourceLeadId must already belong to the same workspace. A reference to another workspace is rejected.

Summary

Leads

Lead create fields: name, email, secondaryEmail, phone, company, companyWebsite, linkedinUrl, title, pronouns, status, notes.

POST /leads/bulk-delete body:

{ "emails": ["avery@example.com"] }

POST /leads/:id/research starts a new research run.

Contacts

Companies

Opportunities

Opportunities have no research report.

Actions and reminders

Action types are meeting, text, email, call, and other. An action is either logged or scheduled.

GET /crm-actions takes objectType and objectId.

Email drafts

POST /email-drafts/:draftId/schedule body:

{
  "recordType": "lead",
  "recordId": "lead_01",
  "scheduledAt": "2026-11-02T15:00:00.000Z",
  "overwrite": false
}

recordType is lead or contact.

Email topics, lists, and campaigns