Existing List as JSON

Audience: Low-code Engineers

Skill Prerequisites: Actions, Lists, APIs, JSON

Returns a list as the response of an API endpoint. Each list entry becomes one JSON object in a JSON array. You can add criteria to return only the entries that match.

The list comes from an earlier action in the API method, such as Create List from SQL or Create List from JSON. This action is only available in APIs. It's a final action: it ends the API method, and no actions after it run.

Typical Use Cases

• Return the rows of a query from a GET endpoint, for example the orders of a customer
• Return only the entries of a list that match a value from the request, for example the orders with a given status
• Feed a JavaScript grid, a mobile app or another system with a JSON array

Don't use it to

• Save a list as JSON in a token, for example to send it to another API or store it. Use List to JSON instead.
• Return a single object. Use Existing Object as JSON or New Object as JSON instead.
• Return nested JSON, or numbers and booleans as real JSON types. Build the JSON with Create JSON Object or List to JSON, and return it with Raw Response.

Related Actions

Action Name	Description
List to JSON	Writes a list as JSON into a token instead of returning it.
Existing Object as JSON	Returns only the first matching list entry, as a JSON object.
New Object as JSON	Returns a JSON object built from name/value pairs.
Raw Response	Returns any content, for example JSON you've built yourself.
File Response	Returns a file.
Download File	Sends a file to download.
Create List from SQL	Creates the list to return.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
List Name	The name of the list to return, for example OrdersList. List names are case-sensitive. If there's no list with this name, the response is null.	Yes	empty string	Yes
Http code	The HTTP status code of the response, for example 200, 201 or 404 Not Found. You can add a description after the number, separated by a space. If it's empty, the status is 200.	Yes	empty string	No
Criteria	Returns only the entries that match. Each row has a Property, for example Status, and a Value, for example [status]. See Criteria.	Only in Value	empty	No
HTTP Headers	Extra response headers. Each row has a Name, for example Cache-Control, and a Value, for example no-cache. Content-Type is application/json unless you set it here.	Yes	empty	No
Allow JSONP	When the request has a callback query string parameter, wraps the JSON in a call to that function, for example myFunction([...]), and sets Content-Type to application/javascript. Without callback, the JSON is returned as usual.	No	false	No

Response

The response is always a JSON array, with one object per entry, in the list's order. An empty list, or a list where no entry matches the criteria, gives [].

[{"OrderNumber":"SO-1001","Total":"49.90","Status":"Open"},{"OrderNumber":"SO-1002","Total":"12.50","Status":"Open"}]

• Every property of the entry is written, with its own name. You can't choose or rename properties here. To do that, reshape the list first with Remap List, or use List to JSON and Raw Response.
• Every value is a JSON string, even when the list holds numbers, booleans or dates, for example a list from Create List from SQL. Numbers and dates are written as text in the site's format, for example "9/27/2026 2:30:00 PM" on an English (US) site. Booleans are "True" or "False". Empty database values are "", not null.
• The objects are flat. A property that points to an object or another list gives the name of that object or list, as a string, not nested JSON.
• Tokens in values are replaced. Property names and values go through token replacement before they're written. A value that contains text in square brackets, for example [Email], may be replaced by the token's value.
• If there's no list with the List Name, the response is null instead of an array. In this case, Http code and Allow JSONP aren't applied, and the status is 200.

Criteria

• An entry is returned when, for every criteria row, its Property value equals the Value.
• The Value can contain tokens, for example [status]. The comparison is exact and case-sensitive, and it's made on the value as text. Open doesn't match open, and 49.9 doesn't match 49.90.
• The Property name isn't case-sensitive.
• Entries that don't have the property are kept. A criteria row on a property the list doesn't have doesn't filter anything, so check the property name.
• Criteria can only test for equality. For other filters, filter the data before the list is created, for example in the SQL WHERE clause.

Considerations

• APIs only. The action is only available in API methods. In other modules, use List to JSON.
• It ends the method. No actions after it run. Put it last, or give it a condition. See Common Parameters.
• List names are case-sensitive. Enter the name exactly as the action that created the list did, for example OrdersList, not orderslist. There's no default list: if List Name is empty, the response is null.
• Http code format. It must start with a number, for example 201 or 201 Created. Other values make the API return an error.
• Values are escaped. Property names and values are written as valid JSON strings, with quotes and special characters escaped.
• Large lists. The whole list is returned in one response. For large lists, filter the data or paginate the list first.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Return the orders of a customer

This action returns every entry of OrdersList, created earlier in the API method, as a JSON array.

{
    "Title": "Existing List as JSON",
    "ActionType": "JsonEntityList",
    "Description": "Return the orders",
    "Parameters": {
        "EntityName": "OrdersList",
        "HttpCode": "200",
        "Criteria": [],
        "Headers": [],
        "AllowJsonp": false
    }
}

2. Return only the orders with a given status

This action returns the entries of OrdersList whose Status equals the status input of the API method. It also tells the caller not to cache the response.

{
    "Title": "Existing List as JSON",
    "ActionType": "JsonEntityList",
    "Description": "Return the orders with the requested status",
    "Parameters": {
        "EntityName": "OrdersList",
        "HttpCode": "",
        "Criteria": [
            {
                "name": "Status",
                "value": "[status]"
            }
        ],
        "Headers": [
            {
                "name": "Cache-Control",
                "value": "no-cache"
            }
        ],
        "AllowJsonp": false
    }
}

Revised 09/27/2026