DocumentationJourney OptimizerJourney Optimizer Guide

Use API call responses in custom actions custom-action-enhancements

Last update: November 10, 2026

CREATED FOR:

  • Experienced
  • Admin
  • Developer

On this page: Capture the JSON response returned by a custom action and use its fields to guide journey decisions, personalize messages, and handle errors.

style
shade-box

Response payload requirements custom-action-enhancements-notes

  • The complete response must be a JSON object. A bare array as the response is not supported.

  • Arrays can be included inside an object. Scalar arrays are supported; heterogeneous arrays are not.

Supported:

{
  "body": ["val1", "val2"],
  "points": 1290
}

Not supported (bare array):

["val1", "val2"]

Not supported (heterogeneous array):

{
  "values": [20, "aafw", false]
}

Configure the custom action config-response

To capture the response of a custom action, define a sample of the payload your endpoint returns.

  1. Create or open a custom action. See Configure a custom action.

  2. Click inside the Response (success response) field.

    {width="80%"}

  3. Paste an example of the successful response your endpoint returns. Verify that the sample’s field types match the actual response. In this example, the local endpoint sends the number of loyalty points and the status of a profile.

    code language-json 
    {
  "customerID": "xY12hye",
  "status": "gold",
  "points": 1290
}

    {width="80%"}

    The sample defines the fields that Journey Optimizer retrieves each time the action is called.

  4. (Optional) To capture a failure payload, select Define a failure response payload and provide an example that matches the payload your endpoint returns when the call fails. For example:

    code language-json 
    {
  "message": "customer not found"
}

    When configured, the failure payload fields are available under the errorResponse node. The shape of the sample should match the real failure response.

  5. Add any required request parameters. In this example, customerID is a query parameter.

    {width="80%"}

  6. Click Save.

Use the response in a journey response-in-journey

Add the custom action to a journey. You can then use the response fields in conditions, subsequent actions, and message personalization.

For example, you can add a condition to check the number of loyalty points. When the person enters the restaurant, your local endpoint sends a call with the profile’s loyalty information. You can send a push if the profile is a gold customer. And if an error is detected in the call, send a custom action to notify your system administrator.

  1. Add your event and the Loyalty custom action created earlier.

  2. In the Loyalty custom action, map the required input parameters, such as the customer ID query parameter with the profile ID. Select Add an alternative path in case of a timeout or error to handle those outcomes separately.

  3. In the success path, add a condition and use the action response fields. In the advanced editor, the response fields are available under the Context node.

  4. Add a push or another action, and personalize your message using the response fields. In this example, the content uses the number of loyalty points and the customer status. The response fields are available under Contextual attributes > Journey Orchestration > Actions.

    note
    NOTE
    Each profile entering the custom action triggers a call, even if the endpoint returns the same response for every profile.

  5. In the timeout and error path, add a condition and use the built-in jo_status_code field to branch on the call outcome. In this example, the condition checks for the http_400 error type. See Error status.

    code language-none 
    @action{ActionLoyalty.jo_status_code} == "http_400"

    If you configured a failure payload, you can also branch on one of its fields. For the example above:

    code language-none 
    @action{ActionLoyalty.errorResponse.message} == "customer not found"

  6. Add a custom action that notifies your organization.

Test mode logs test-mode-logs

Use test mode to inspect the payload returned by the action in the actionsHistory section of the logs. For failed calls, the logs include the failure payload if one is configured. This is useful for debugging.

Error status error-status

The jo_status_code field is available even when no response payload is defined. Possible values include:

Value
Meaning
http_<code>
HTTP status code returned by the API call, such as http_200 or http_400
timedout
The call timed out
capped
The call was blocked by capping
internalError
An internal error occurred

An action call is considered in error when the returned HTTP code is greater than 2xx or when another error occurs. In that case, the journey follows the configured timeout or error branch.

Only newly created custom actions include the jo_status_code field by default. To use it with an existing custom action, update and save the action. For example, you can update its description.

If no failure response payload is configured, the errorResponse node is not available.

Expression syntax exp-syntax

Reference a response field with:

@action{<action name>.<field path>}

For example:

@action{ActionLoyalty.status}

To provide a default value:

@action{<action name>.<field path>, defaultValue: <expression>}

For example:

@action{ActionLoyalty.points, defaultValue: 0}
@action{ActionLoyalty.points, defaultValue: @event{myEvent.newPoints}}

For collections, use currentActionField to refer to the current item:

count(
  @action{MyAction.MyCollection.all(
    currentActionField.description == "abc"
  )}
)

See Field references and Collection management functions.

Personalize native-channel messages response-in-channels

Use custom action response fields in supported native-channel personalization (email, push, mobile messages). For arrays and nested data, see Iterate over contextual data with Handlebars.

Troubleshooting troubleshooting

Symptom
Check
Response fields are unavailable
Confirm that the Response sample is valid JSON and reflects the endpoint’s response structure and field types.
The response cannot be used because it is an array
Return an object instead, placing the array inside a field.
Some array values are unavailable
Confirm that the array is not heterogeneous.
jo_status_code is missing on an existing action
Update and save the action. The field is included by default only on newly created actions.
errorResponse is unavailable
Configure and save a failure response payload.
The call follows the timeout or error branch
Inspect jo_status_code and, if configured, the failure payload in the test mode logs.

Additional resources

AI Knowledge Reference

This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.

For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.

  • TL;DR: This page explains how to capture the response payload returned by a custom action’s API call and leverage it to orchestrate journeys, personalize messages, and handle errors.

Intents:

  • Configure a custom action to capture success and failure response payloads
  • Leverage response payload fields in conditions, other actions, and message personalization
  • Handle errors and timeouts using the jo_status_code field and the errorResponse node
  • Inspect custom action responses through test mode logs
  • Use the expression syntax to reference response fields, including default values and collections

Glossary:

  • Response payload: The example payload pasted in the Response (success response) field whose fields are retrieved on each call (product-specific)
  • Error response payload: The payload captured when a call fails, enabled by selecting Define a failure response payload, exposed under the errorResponse node (product-specific)
  • jo_status_code: A built-in field, always available even when no response payload is defined, that carries the call outcome (product-specific)
  • actionsHistory: A section shown in test mode logs that displays the payload returned by the external endpoint (product-specific)
  • currentActionField: A reference used to access the current item when manipulating collections in a custom action response (product-specific)
  • Test mode: The mode through which you access status logs related to custom action responses (product-specific)

Guardrails:

  • The response payload must be a JSON object; a bare top-level array as the whole response is not supported, so place the array inside a field (for example body).
  • Scalar arrays are supported in the response payload, but heterogeneous arrays are not supported.
  • Only newly created custom actions include the jo_status_code field out-of-the-box; to use it with an existing custom action you need to update the action, for example by updating the description and saving.
  • An action call is considered in error when the returned http code is greater than 2xx or if an error occurs, and the journey flows to the dedicated timeout or error branch.
  • If an error response payload is configured, its fields are exposed under the errorResponse node for failed calls; if none is configured, that node is not available.
  • Each profile entering the custom action triggers one call, even if the response is always the same.

Terminology:

  • Canonical name: API call response in custom actions — Acronym: n/a — variants: custom action response, response payload
  • Synonyms: “success response” = “Response field”
  • Do not confuse: “Response” (success response payload) ≠ “Error Response” (failure response payload defined via Define a failure response payload)
  • jo_status_code values: http_ (for example http_200 or http_400), timedout (timeout error), capped (capping error), internalError (internal error) ``

`FAQ:

Q: Can the whole custom action response be an array? — No; the response payload must be a JSON object, so place the array inside a field (for example body). A bare top-level array as the whole response is not supported. Q: Which array types are supported in the response payload? — Scalar arrays are supported; heterogeneous arrays are not supported. Q: Why does an existing custom action not expose the jo_status_code field? — Only newly created custom actions include it out-of-the-box; update the existing action, for example by updating the description and saving, to add it. Q: When is an action call considered in error? — When the returned http code is greater than 2xx or an error occurs, after which the journey flows to the dedicated timeout or error branch. Q: Where can the returned payload be inspected? — Through test mode logs, in the actionsHistory section that displays the payload returned by the external endpoint. Q: Can response payload fields be used in native channels? — Yes, response payload fields from custom actions can be used in native channels (email, push, mobile messages) for message personalization.

Personas:

developer: Can leverage API call response payload fields in conditions, other actions, and message personalization. Can reference action response fields using the expression syntax, for example @action{ActionLoyalty.status}. Can use currentActionField to access the current item while manipulating a collection in a custom action response. Where: “Expression syntax”. admin: Can configure the custom action by pasting an example payload into the Response field to capture fields returned by the call. Can enable an error response payload by selecting Define a failure response payload in the custom action configuration. The page states that only newly created custom actions include the jo_status_code field out-of-the-box. Where: “Configure the custom action”.

Onboarding:

Level: Experienced First minimal step: Paste an example of the payload returned by the call. Success check: Each time the API is called, the system retrieves all the fields included in the payload example. Previous: Before configuring the response payload, create the custom action: Configure a custom action (action/about-custom-action-configuration.md) Next: To iterate over arrays and nested data from the response in messages: Iterate over contextual data (personalization/iterate-contextual-data.md)`

``

recommendation-more-help
journey-optimizer-help