SfSkills Domains Docs GitHub

Home / flow / flow-external-services

flow-external-services

Use when calling external REST APIs from Salesforce Flow without writing Apex: registering API specs as External Services, using generated invocable actions in Flow Builder, using Flow's built-in HTTP Callout action (GA Spring '24+), configuring Named Credentials for authentication, mapping inputs/outputs, and handling fault paths.

Open the skill folder on GitHub

Flow External Services

This skill activates when a practitioner needs to call an external REST API directly from Salesforce Flow — either by registering an OpenAPI spec via External Services or using Flow's built-in HTTP Callout action — without writing Apex. It covers registration, action configuration, Named Credential selection, input/output mapping, response parsing, fault handling, and governor limit constraints.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

External Services: Spec-Driven Invocable Actions

External Services is a Salesforce platform feature under Setup > Integrations > External Services. It ingests an OpenAPI 2.0 or 3.0 spec, validates it against Salesforce's supported subset, and generates strongly-typed invocable actions — one per operation defined in the spec. These actions appear in Flow Builder's Action palette under the external service's label.

Registration requirements:

Versioning: External Services supports multiple spec versions under one registration. When you import an updated spec, Salesforce can maintain the previous version so existing Flow actions continue to work while you migrate.

Flow's Built-in HTTP Callout Action (Spring '24+ GA)

For situations where an OpenAPI spec is not available or the integration is simple enough not to warrant full External Services registration, Flow Builder (Spring '24 GA) offers a built-in HTTP Callout core action. You configure it declaratively:

The HTTP Callout action is simpler to configure than a full External Services registration but gives less type safety — response fields are not schema-validated and must be manually mapped.

Named Credentials: Authentication Gateway for Flow Callouts

All Flow callouts — whether via External Service actions or HTTP Callout actions — must reference a Named Credential. The Named Credential:

  1. Supplies the base URL (so no hardcoded endpoints in Flow).
  2. Handles authentication transparently (OAuth token injection, JWT signing, basic auth headers).
  3. Controls which users can call out via External Credential principal and Permission Set assignment.

If the Named Credential's External Credential principal does not have the running user's Permission Set assigned, the callout fails at runtime with a generic authentication error. This is the most common first-run failure.

Error Handling: Fault Paths Are Mandatory

External Service actions and HTTP Callout actions are fallible elements. Any network failure, timeout, non-2xx HTTP response (for External Services), or malformed response can cause the action to route to its fault path.

In Flow Builder, every External Service action and HTTP Callout action exposes a fault connector. If this connector is not wired, a failure terminates the Flow interview and throws a generic platform error — which for screen flows shows a poor user experience, and for autolaunched flows causes the caller to receive an unhandled exception.

Minimum fault pattern:

  1. Wire the fault connector to a dedicated fault path.
  2. Capture $Flow.FaultMessage in a Text variable.
  3. Route to a user-safe screen (screen flows) or log/notify (autolaunched flows).
  4. Consider whether the failure should be retried, escalated, or silently swallowed based on business requirements.

Common Patterns

Pattern 1: Register an OpenAPI Spec and Use the Generated Action in Flow

When to use: The external API publishes a machine-readable OpenAPI spec and you want typed, auto-generated actions with named input/output fields.

How it works:

  1. Confirm Named Credential exists for the target service (see named-credentials-setup).
  2. Navigate to Setup > Integrations > External Services > Add an External Service.
  3. Provide the spec URL or upload the file. Select the Named Credential. Click Save.
  4. Salesforce validates the spec. Review any warnings — unsupported schema features are flagged here.
  5. Open Flow Builder and add an Action element. Search for the external service name. Select the operation.
  6. Map required input fields (scalar types, text, number, boolean). For body objects, use a Flow record variable typed to a matching Apex class if one was generated, or individual field assignments.
  7. Store output fields in Flow variables of the correct type.
  8. Wire the fault connector. Capture $Flow.FaultMessage.
  9. Test using Flow's debug mode — mock response is not available, so a real endpoint (or a sandbox of the external service) is required.

Why not the HTTP Callout action: If the spec is available and the API has multiple operations, External Services gives compile-time field validation, auto-complete in Flow Builder, and easier maintenance when the API contract changes.

Pattern 2: Declarative HTTP Callout Without a Spec

When to use: No OpenAPI spec exists, the API has a single simple operation, or you want the fastest path to a working callout without spec maintenance overhead.

How it works:

  1. Confirm Named Credential exists.
  2. In Flow Builder, add a Core Action element. Select HTTP Callout from the action list.
  3. Configure:
    • Named Credential: select from dropdown.
    • Invocable Action Name: a label used to identify this step.
    • Method: GET / POST / etc.
    • Path: resource path relative to Named Credential URL.
    • Headers: add Content-Type: application/json for POST/PUT requests.
    • Request Body: paste the JSON template or build it with a Text formula variable.
  4. The action outputs: Response_Body (Text), Response_Status_Code (Number), Response_Headers (Text).
  5. Parse Response_Body using a Transform element or a lightweight Apex method if the JSON is deeply nested.
  6. Check Response_Status_Code in a Decision element — route non-2xx codes to an error path independently of the fault connector (the HTTP Callout action only faults on network/timeout errors, not 4xx/5xx responses).
  7. Wire the fault connector for network-level failures.

Why not External Services: Speed and simplicity when spec is unavailable, the API surface is small, or the integration is short-lived.

Pattern 3: Parsing Complex JSON Responses

When to use: The external service returns a nested JSON object or an array, and you need to extract specific fields into Flow variables.

How it works:

External Service invocable actions return output as typed variables that match the spec schema — scalars are directly assignable to Flow variables, and objects/arrays are accessible as Apex-typed variables or Flow sObject-compatible records if they match a custom object structure.

For HTTP Callout action responses (raw text), use:

  1. Flow Transform element (available in flows alongside HTTP Callout): maps JSON path expressions to Flow variables. Useful for flat or moderately nested responses.
  2. Apex Invocable method: if the response is deeply nested, polymorphic, or requires conditional extraction, pass Response_Body to a lightweight @InvocableMethod that parses and returns structured output. Keep the Apex logic minimal — the goal is parsing, not business logic.
  3. Collection variables: for array responses (e.g., a list of records), use Loop elements over a collection variable populated by the External Service action's list output.

Decision Guidance

SituationRecommended ApproachReason
API has an OpenAPI 2.0/3.0 spec and multiple operationsExternal Services registrationTyped actions, auto-complete, spec-versioning support
API has no spec or only one endpointHTTP Callout core actionFaster setup, no spec maintenance
Authentication required (always)Named Credential (Enhanced model)Platform-managed auth, no hard-coded secrets in Flow
Record-triggered flow needs to call external APIAsync pattern: Platform Event or Queueable ApexSynchronous callouts are not allowed in record-triggered transactions
Response is a flat JSON object with known fieldsTransform element or External Service output mappingNo Apex needed
Response is deeply nested or polymorphic JSONLightweight Apex @InvocableMethod for parsingFlow Transform cannot handle arbitrary depth
Screen flow calling external APIWrap action in a separate autolaunched subflowIsolates callout fault path from screen navigation logic
Batch / high-volume contextAvoid Flow callouts; use Queueable or Batch ApexFlow callout limit is per-transaction; high-volume processing exhausts it quickly
Flow External Services vs Apex callouts for simple CRUDFlow External Services if no custom logic neededLower maintenance, declarative, no deployment unit for code changes

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm the external API endpoint, authentication type, whether a spec file exists, and the Flow type (screen, autolaunched, record-triggered). If record-triggered, identify an async dispatch pattern before proceeding.
  2. Set up Named Credential — verify or create a Named Credential and External Credential following the named-credentials-setup skill. Confirm Permission Set is assigned to the External Credential principal before testing.
  3. Choose registration method — if an OpenAPI spec is available, register via External Services (Setup > Integrations > External Services). If not, proceed with the HTTP Callout core action in Flow Builder.
  4. Build the Flow — add the External Service action or HTTP Callout action, map all required inputs, and wire output variables to correctly typed Flow variables. Add a Decision element to check HTTP status code for non-2xx handling (HTTP Callout only).
  5. Wire fault connectors — connect every External Service or HTTP Callout element's fault path to a dedicated error handling branch. Capture $Flow.FaultMessage. For screen flows, display a friendly message. For autolaunched flows, log or notify.
  6. Test end-to-end — run Flow debug with real credentials against the target environment. Confirm successful response, then deliberately test a failure scenario (wrong path, revoked token) to verify the fault path.
  7. Review checklist — complete the checklist below before promoting to production.

Review Checklist

Run through these before marking a callout Flow complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Record-triggered flows cannot make synchronous callouts — Attempting a direct HTTP callout (via External Services action or HTTP Callout action) inside a record-triggered before-save or after-save flow throws a System.CalloutException: You have uncommitted work pending error at runtime. The fix is to dispatch work asynchronously via a Platform Event, a scheduled path, or a Queueable Apex job invoked from the flow.
  2. HTTP Callout action does not fault on 4xx/5xx responses — Unlike External Services invocable actions (which route to the fault path on non-2xx responses depending on the spec configuration), the built-in HTTP Callout action only faults on network errors and timeouts. A 404 Not Found or 500 Internal Server Error response is returned with a status code variable and does not automatically trigger the fault connector. You must add an explicit Decision element checking Response_Status_Code >= 400 to route these to an error path.
  3. External Services does not support all OpenAPI features — Salesforce validates specs against a supported subset. Schemas using oneOf, anyOf, allOf composition, recursive $ref chains, or enum arrays on request body parameters may fail to import or produce incomplete action signatures. Always test the spec import in a sandbox before committing an integration design that depends on full spec coverage.
  4. Named Credential URL and path double-slash — If the Named Credential base URL ends with a trailing slash and the resource path in the HTTP Callout action or spec starts with a /, the concatenated URL contains //. Some APIs reject this. Always strip the trailing slash from the Named Credential URL and ensure paths start with /.
  5. External Service action outputs are Apex-typed, not natively sObject — Output variables from External Service invocable actions are typed as Apex wrapper classes generated from the spec. They cannot be directly assigned to standard Flow record (sObject) variables unless the field names match exactly. Explicitly map each output field to the target sObject variable's field in a separate Assignment element.

Output Artifacts

ArtifactDescription
External Service registrationRegistered API spec with generated invocable actions visible in Flow Builder
Named Credential configurationEndpoint + auth setup required before Flow callouts can execute
Flow with callout actionConfigured External Service or HTTP Callout action with input mapping, output capture, and fault path
Response parsing patternTransform element mapping or Apex @InvocableMethod for structured JSON extraction
Review checklist completionCompleted checklist confirming fault paths, auth, status code handling, and limit awareness

Dependencies

Package files