Use JSON content modelling when the external API sends or expects JSON.

Payloads represents JSON as an Element tree. Each Element describes one part of the structure: an object, array, string, number, boolean, or null value. That tree gives admins a readable model of the API body instead of hiding the contract inside code or a long text field.

The main idea is simple: model the shape first, then map the leaf values from Salesforce data, inbound data, Dynamic Inputs, Credentials, static values, or Transformations.

For the core mapping concepts, see Understand Elements and mapping.

Every body has a root Element named $.

The root represents the whole body Payloads will parse or build. It is an object by default, which is the right choice for most JSON APIs. Keep it as an object when the JSON body looks like this:

Change the root to an array only when the whole body is an array:

Do not create a separate standard Salesforce Element record manually. Build and edit the structure from the Payload UI so the tree, mapping controls, and available source values stay in sync. The custom UI also makes it much easier to see how parent and child Elements fit together.

The custom Payload UI shows the JSON structure as a tree, including the root Element, nested values, arrays, and mapped response values.

Use Object for a named JSON object, and use Array when a value can contain repeated entries.

Use String, Number, Boolean, or Null for leaf values. A leaf value is the point where Payloads reads or writes an actual value rather than another container.

The Element type should match the API contract. If the external API expects a number, model that Element as Number even if the value comes from a Salesforce field that displays as text in the UI. Matching the contract here reduces surprises when you inspect the generated Job body later.

JSON and form-style structures are both modelled as visible Elements, so each mapped value can be reviewed before testing.

Use nested Object Elements when the API groups values under a named object.

For example, a checkout API may expect customer details under customer, with fields below it for name, email, and account id. Model that as a customer Object with child Elements, rather than flattening the values into unrelated top-level fields.

Keep object names exactly aligned with the external API documentation. Payloads uses the Element path to build the final JSON, so a small naming difference can change the request body.

Use Array Elements when the JSON structure can repeat.

An array should normally be linked to a repeating source. For an outbound request, that might be a child relationship from a Data Query. For an inbound request, that might be an array in the incoming body.

In the Stripe checkout example, the line_items array is mapped from the queried OpportunityLineItems child records. Each child record becomes one entry in the outbound array, and the Elements inside that array can use fields from the current line item.

For the index tree rules that control which fields are available inside arrays, see Map outbound request bodies.

Leaf Elements are where values come from. Once the structure is correct, most of the useful work happens at the leaves.

Depending on the Payload section, a leaf value can come from:

Only model fields that the integration uses. You do not need to reproduce every field in a large API response if Payloads only needs a few values for mapping, response output, or troubleshooting. A smaller tree is usually easier for another admin to understand.

When you import a sample JSON body, Payloads can create an Element tree from the sample.

Use realistic examples, but remove sensitive values first. After import, review arrays and sample-only fields. A sample with one line item still needs the correct array structure if the live API can send or receive many items.

Import is a starting point, not a substitute for understanding the API contract. Review the imported tree before you rely on it in a live Payload.

Before testing, check that:

After testing, open the Job and compare the outbound or inbound body with the Element tree.