Salesforce REST API Connector Guide

The Salesforce connector lets Tealfabric workflows read and write CRM data in standard and custom Salesforce objects. This guide covers secure authentication setup, practical record operations, and reliability patterns for production integrations.

When to use this connector

Use this connector when workflows must create or update CRM records, query pipeline data, or synchronize account and contact state with external systems. It is especially useful for sales and support automations where CRM accuracy drives downstream decisions. Aligning ownership of object fields between systems helps prevent conflicts and accidental overwrites.

Prerequisites

Before configuring the integration, create or confirm a Salesforce Connected App with required API permissions and OAuth settings. Ensure the integration user has object-level and field-level access for all records you plan to touch. Validating permissions up front reduces production failures in record writes and SOQL queries.

Configuration reference

Connector credentials and tokens are stored in integration configuration and reused by runtime operations. Keep secrets secure and rotate credentials according to policy.

• instance_url (required): Salesforce instance base URL.
• client_id (required): Connected App consumer key.
• client_secret (required): Connected App consumer secret.
• username (required): Salesforce integration username.
• password (required): Password for the integration user.
• security_token (required): Salesforce security token for the integration user.
• access_token (optional): Access token used for API calls.
• timeout_seconds (optional): Request timeout for connector calls.

Create and update CRM records

The send operation handles create, update, and delete calls on Salesforce objects. Use API field names and object endpoints consistently to keep request behavior predictable.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type SalesforceWriteResult = {
  id?: string;
  success?: boolean;
  errors?: string[];
};

async function createSalesforceAccount(
  integrationId: string
): Promise<SalesforceWriteResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        endpoint: "sobjects/Account",
        method: "POST",
        data: {
          Name: "Acme Manufacturing",
          Phone: "555-1234",
          Industry: "Manufacturing",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    data?: { data?: SalesforceWriteResult; response?: SalesforceWriteResult };
  };
  if (!payload.data?.data) throw new Error("Missing Salesforce write payload");
  return payload.data.data;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "endpoint": "sobjects/Account",
    "method": "POST",
    "data": {
      "Name": "Acme Manufacturing",
      "Phone": "555-1234",
      "Industry": "Manufacturing"
    }
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "data": {
      "id": "001XXXXXXXXXXXXXXX",
      "success": true
    },
    "response": {
      "id": "001XXXXXXXXXXXXXXX",
      "success": true
    }
  }
}

Query records with SOQL

Use receive with the query endpoint to fetch targeted records for workflow logic and reporting. Keep SOQL clauses selective and include explicit limits for better performance.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type AccountSummary = { Id?: string; Name?: string; Phone?: string };

async function fetchTechnologyAccounts(
  integrationId: string
): Promise<AccountSummary[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        endpoint: "query",
        query: {
          q: "SELECT Id, Name, Phone FROM Account WHERE Industry = 'Manufacturing' LIMIT 20",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    data?: { data?: AccountSummary[]; message_count?: number; total_size?: number };
  };
  if (!payload.data?.data) throw new Error("Missing Salesforce query payload");
  return payload.data.data;
}

Validate and troubleshoot safely

Run test after credential changes, Connected App updates, or API version upgrades. The test operation validates all required Salesforce configuration parameters (instance_url, client_id, client_secret, username, password, security_token); other operations rely on stored credentials or an existing access_token and obtain a new token when needed. Most failures come from invalid token input, missing field permissions, or hitting org API limits. Capture execution IDs and Salesforce error payloads in logs to simplify incident response.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "message": "Salesforce API connection test successful",
    "details": {
      "instance_url": "https://yourinstance.salesforce.com",
      "api_version": "v58.0",
      "sobjects_count": 842
    }
  }
}

Additional references

For object schema and query syntax, refer to the Salesforce REST API documentation, SOQL reference, and Salesforce object reference. Documenting field ownership and sync direction per object helps keep integrations maintainable.