Tutorial · Salesforce

Salesforce AI API: build a custom copilot

A Salesforce copilot should read through a least-privilege integration user, answer with cited records, and never change a record without an explicit approval.

Short answer. Create an external client app with OAuth, give the integration user only the objects and fields it needs, describe the schema before querying, page SOQL results with nextRecordsUrl, enforce field-level security and sharing in your service, and require human approval before any write-back. Watch the org's daily API allocation and the model's token spend separately.

1. Authenticate with an external client app

Salesforce restricted new connected app creation as of Spring '26 and recommends external client apps instead. If you are starting now, use an external client app where your edition supports it. For server-to-server work, enable the OAuth 2.0 client credentials flow and assign an integration user; for per-user context, use the JWT bearer flow. The username-password flow is deprecated and should not be used for new integrations.

curl -s -X POST \
  "https://$MY_DOMAIN.my.salesforce.com/services/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SF_CLIENT_ID" \
  -d "client_secret=$SF_CLIENT_SECRET"

The client credentials flow does not support login.salesforce.com or test.salesforce.com; use the org's My Domain URL. The response includes access_token and instance_url. Use the returned instance URL for every subsequent call; do not hard-code it.

2. Describe objects and fields first

Do not let the model invent field names. Call GET /services/data/vXX.X/sobjects/{Object}/describe and build an allowlist from fields where accessible is true. Keep createable and updateable separately for write proposals. Pin an API version in the URL and check /services/data for the versions your org exposes.

ObjectUseful fieldsNote
AccountId, Name, Industry, OwnerIdOwnership affects sharing.
ContactId, Name, Email, AccountIdEmail may be null or duplicated.
OpportunityId, Name, StageName, Amount, CloseDateStage and amount are high-impact writes.
CaseId, Subject, Status, PriorityStatus values are org-specific.

3. Query with SOQL, carefully

Run queries through GET /services/data/vXX.X/query?q=.... A synchronous query returns up to 2,000 records per call; if more remain, the response has done: false and a nextRecordsUrl. Follow that URL until done is true.

curl -s --get "https://$MY_DOMAIN.my.salesforce.com/services/data/v66.0/query" \
  -H "Authorization: Bearer $SF_ACCESS_TOKEN" \
  --data-urlencode "q=SELECT Id, Name, StageName, Amount, CloseDate FROM Opportunity WHERE StageName = 'Negotiation' ORDER BY CloseDate ASC LIMIT 200"

SOQL has no bind parameters in the REST query string, so never concatenate raw user input. Validate identifiers against the describe allowlist and escape string literals. Keep the URI under roughly 2,000 characters; Salesforce's combined URI and header limit is 16,384 bytes. For long queries, split the query or use the Composite API rather than building an oversized URL.

4. Enforce field-level security and sharing

The API enforces field-level security and record sharing for the integration user, but that is not a substitute for your own authorization layer. An integration user with View All Data or Modify All Data can see far more than the person using the copilot. Use a dedicated user with a minimum permission set, and test with a restricted user before rollout.

ControlWhere it is enforcedWhat to test
Field-level securitySalesforce, for the integration userA hidden field is absent, not blank.
Record sharingSalesforce sharing rules and role hierarchyA record outside the user's access is not returned.
Object permissionsPermission setsNo create or update on objects the agent only reads.
Your retrieval filterYour serviceContext never contains a record the user cannot open.

5. Write back behind approval

Generate a proposed change as a diff, not a mutation. Show the record, the field, the old value and the new value, and require an explicit approval. Then apply it with PATCH /services/data/vXX.X/sobjects/{Object}/{Id} and log the approval, actor and response.

PATCH /services/data/v66.0/sobjects/Opportunity/$SF_OPPORTUNITY_ID
{
  "StageName": "Proposal",
  "CloseDate": "2026-12-15"
}

High-impact fields such as Amount, StageName, OwnerId and CloseDate should never be auto-written. Add an idempotency key so a retry does not apply the same change twice, and re-read the record immediately before the write to catch a concurrent edit.

6. Governor limits and cost

LimitValue to plan forImplication
Daily API requestsDeveloper: 15,000. Enterprise: 100,000 + licenses × allocation.One copilot query can consume several calls.
Concurrent long requests25 in production; 5 in Developer/Trial.Batch jobs can crowd out interactive users.
REST/SOAP timeout10 minutes, except query calls.Do not run long model calls inside a Salesforce request.
SOQL rows per call2,000Page with nextRecordsUrl.
URI plus headers16,384 bytesKeep SOQL short; prefer Composite for long queries.

Check the org's real numbers with GET /services/data/vXX.X/limits and the Sforce-Limit-Info response header. Model cost is separate: each answer uses retrieved record text plus the user question. On Plugsky, paid plans start at $8/month; Builder and Scale have no monthly token cap under fair-use limits. See pricing. Plan changes and overage purchases are billing actions; require the account owner's approval.

For the sales workflow, see build an AI sales agent and how to build sales agents.

FAQ

Can I use an external model with Salesforce?

Yes. Keep Salesforce as the system of record, run an external service that authenticates with OAuth, retrieves only permitted records, and calls the model outside the Salesforce request.

Should I use a connected app or an external client app?

Use an external client app for new work where your edition supports it. Salesforce restricted new connected app creation as of Spring '26 and recommends external client apps.

How do I respect field-level security?

Use a dedicated integration user with a minimum permission set, build field allowlists from the describe response, and test with a restricted user. Do not use an admin user for the copilot.

What are the Salesforce API limits?

Daily API requests depend on edition and licenses; Developer Edition has 15,000. Production allows 25 concurrent long-running requests, REST calls time out at 10 minutes, and SOQL returns up to 2,000 rows per call. Check /limits for the org's real numbers.

Can the agent update records automatically?

It can propose updates, but amount, stage, owner and close date should require human approval. Apply approved changes with PATCH and log the actor, approval and response.

Sources checked 20 November 2026: Salesforce external client app OAuth; Salesforce REST API query; Salesforce API request limits. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.