Configure an API Pull From Salesforce Payload
Use an API Pull From Salesforce Payload when another system needs to request Salesforce data through a Payloads endpoint.
The external system starts the interaction. Payloads receives the request, reads headers or parameters if needed, queries Salesforce, then builds the response.
If the external system is sending data that Salesforce should store, use Configure an API Push Into Salesforce Payload instead.
When to use it
Use an API Pull From Salesforce Payload when you need to:
expose selected Salesforce data to another system
control the query from inside Payloads
use request parameters to filter Salesforce data
return a shaped JSON, XML, form URL encoded, or plain text response
avoid building a custom Apex REST endpoint for a simple read-only API
The Stripe demo Payload lets an external system request payment status by session id. Payloads reads the request parameter, queries the matching Opportunity, and returns a small response.
Payload structure
An API Pull From Salesforce Payload has an inbound Request side and an outbound Response side.
The Request side can model inbound Headers and Parameters. It does not model an inbound body, because this type is for read-style requests where the caller asks Salesforce for data.
The Response side contains Data Queries, Body, and Headers. Those sections decide what Salesforce data is fetched and how it is returned.
The Endpoint section connects the Payload to the URL another system calls.
The API Pull From Salesforce layout reads values from the inbound Request, runs Data Queries, and builds the Response from Salesforce data.
Header fields
Start with the main fields on the Payload record.
Type: choose API Pull From SF.
Integration: choose the Integration this API belongs to.
Inbound Content Type: choose the format Payloads should use for inbound request values.
Outbound Content Type: choose the response format Payloads should return.
The outbound content type is especially important. It controls how Payloads serialises the response body you build.
Request Headers
Use Request Headers when the caller sends values Payloads needs to read.
Examples include tenant identifiers, source system names, correlation ids, or values used in query filters. Do not model every possible header. Model the headers that are meaningful to the Payload.
The API Pull demo captures caller metadata before Payloads builds the Salesforce-backed response.
Request Parameters
Use Request Parameters for values that filter or identify the Salesforce data to return.
The Stripe demo uses a stripeSessionId parameter. That value is then used by the Data Query to find the relevant Opportunity.
Give parameters clear names, and keep them stable. External systems will depend on them once the endpoint is in use.
Data Queries
Data Queries are the centre of an API Pull From Salesforce Payload.
Each query defines the Salesforce object, filter, and record limit Payloads uses before building the response. The filter can use request parameters, static values, or other supported filter inputs.
Keep queries intentionally small. This type works best when the endpoint returns a focused response for a specific use case, not a broad Salesforce data export.
The Data Query uses the inbound request value to find the Salesforce record that should drive the response.
Response Body
The Response Body tab defines the content returned to the caller.
Build Elements for the fields the external system needs. Each Element can use a value from a Data Query, a Static Value, a Dynamic Input, or a Transformation.
Keep the response shape stable once the external system starts using it. If you need a materially different response later, consider a new Payload or endpoint version.
Response Headers
Use Response Headers when the caller expects metadata outside the body.
Common examples include content type, cache hints, correlation ids, or custom status headers. Keep these aligned with the external system's API contract.
Endpoint
The Endpoint section defines the URL and method exposed by Payloads.
GET is the usual method for pull-style APIs, but the method should follow the contract agreed with the external system.
If you need separate read behaviours, create separate Payloads and endpoints. That keeps each API easier to document, secure, and troubleshoot.
What to check before testing
Before you test the endpoint, check that:
required request Parameters and Headers are configured
Data Query filters use the right parameter names
record limits are appropriate
the Response Body only exposes fields the external system should receive
the outbound content type matches the response structure
the Endpoint method and URL match the external system's call
After a test call, open the Job record and confirm the inbound parameters, query results, response body, and response status.