Salesforce API v2

Last updated: 3 November 2026

This is the Salesforce package API. The caller is a YouEx user who has installed the package into one workspace.

The current contract is the API reference (PDF). For the in-app connection, owners and admins on a Salesforce-entitled plan use Workspace Settings → Integrations.

Salesforce API v2 is included on Professional and Enterprise (salesforcePackage). Use it for CRM, research, enrich, and agents from the package, and for lead sync through bulk upsert.

Base URL

https://engage.youex.ai/api/integrations/salesforce/v2

Paths below are relative to that base.

Authentication

Authorization: Bearer <access_token>
Content-Type: application/json

The token is an Auth0 access token for the Salesforce audience. A scope check passes when the token has any one of the scopes listed for that call.

youex.salesforce.read covers every read scope below. youex.salesforce.write covers every write scope below.

Discovery

These routes do not require a token.

Install and account

CRM calls require a connected installation.

Changing the shared selection on POST /workspaces/:workspaceId/select also needs workspace write.

POST /install body:

{
  "workspaceId": "ws_123",
  "salesforceOrgId": "00Dxx0000000001",
  "salesforceUserId": "005xx0000000001",
  "salesforceUserEmail": "user@example.com",
  "packageVersion": "1.2.0"
}

salesforceUserId, salesforceUserEmail, and packageVersion may be null.

POST /uninstall body:

{ "workspaceId": "ws_123" }

Limits and errors

• API routes: 180 requests per minute per IP.
• Install routes: 30 requests per minute per IP.
• Responses include standard rate-limit headers.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope. Expected one of: youex.salesforce.leads.write, youex.salesforce.write",
    "retryable": false
  }
}

A suspended workspace returns 402. Research and enrich also count against the workspace's monthly allowances.

CRM records

:workspaceId is the installed YouEx workspace. :id accepts the YouEx id or the stored Salesforce id.

Create bodies may include /_salesforceId. Unknown keys are rejected.

List query parameters are limit (1–200), cursor, and search, plus the filter named in the table.

A list response is:

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

Contacts, companies, and opportunities use the same shape with contacts, companies, or opportunities. A single record is { "lead": {} } (or contact, company, opportunity).

Bulk upsert accepts 1–200 items:

{
  "items": [
    { "/_salesforceId": "00Qxx0000000001", "name": "Avery Smith", "email": "avery@example.com" }
  ]
}

Response:

{
  "totalReceived": 1,
  "insertedCount": 1,
  "updatedCount": 0,
  "skippedCount": 0,
  "notFoundIds": [],
  "results": [
    {
      "index": 0,
      "action": "inserted",
      "inputId": "00Qxx0000000001",
      "recordId": "lead_01",
      "code": null,
      "message": null
    }
  ]
}

action is inserted, updated, or skipped.

Leads

Writable lead fields match the CRM lead, including name, email, secondaryEmail, phone, secondaryPhone, linkedinUrl, company, companyWebsite, title, status, notes, tags, customFields, contactId, companyId, and opportunityId.

Contacts

Companies

Opportunities

closePlan and closingNotes accept null and are stored as empty strings.

Contact, company, and opportunity writes use the same customer fields as the Zapier CRM records, plus /_salesforceId and customFields.

Shared status and stage values are the same as the REST API.

Research, enrich, and contact search

Research and enrich are asynchronous. The start call returns 202 with a job id. Poll the status path until finished is true. A research or enrich that is already running returns 202 with finished: false and does not start a second run.

Contact search body:

{ "jobTitle": "VP Sales", "exactMatch": false, "limit": 10 }

limit is 1–100 and defaults to 10. The start response includes contactSearchId, companyId, status (pending, processing, completed, failed), and finished.

Research and enrich status bodies include status, finished, success, failed, data, and error (code and message) when the job failed.

Fields, items, and agents

Body for POST /workspaces/:workspaceId/items:

{
  "instance": "lead",
  "fieldKeys": ["name", "email", "status"],
  "limit": 100,
  "cursor": null,
  "search": "acme"
}

fieldKeys has 1–200 entries. limit is 1–1000. search and filter cannot be sent together. Lead items require leads read. Other instances require workspace read.

The response is { "workspaceId", "instance", "items", "total", "hasMore", "nextCursor" }.