Existing Object as JSON

Audience: Low-code Engineers

Skill Prerequisites: Actions, Lists, APIs, JSON

Returns one entry of a list as the response of an API endpoint, as a JSON object. It returns the first entry that matches the criteria, or the first entry of the list if there are no criteria.

Despite its name, it reads a list, for example one from Create List from SQL. It doesn't read objects made with Create Object. 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 a single record from a GET endpoint, for example the customer with a given ID
• Return the row that a query found, for example the result of a lookup by email

Don't use it to

• Return all entries of a list. Use Existing List as JSON instead.
• Return an object made with Create Object. Turn it into JSON with Create JSON Object, and return it with Raw Response.
• Return values from tokens. Use New Object as JSON instead.

Related Actions

Action Name	Description
Existing List as JSON	Returns all matching list entries, as a JSON array.
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.
List to JSON	Writes a list as JSON into a token instead of returning it.
Create List from SQL	Creates the list to read the entry from.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
List Name	The name of the list to read, for example CustomerList. 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 or 201 Created. You can add a description after the number, separated by a space. If it's empty, the status is 200. It isn't used when the response is null.	Yes	empty string	No
Criteria	Picks the entry to return. Each row has a Property, for example CustomerId, and a Value, for example [id]. 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 one JSON object with every property of the entry, with its own name.

{"CustomerId":"42","Name":"Jane Doe","Email":"jane@example.com","IsActive":"True"}

• 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. Booleans are "True" or "False". Empty database values are "", not null.
• The object is flat. A property that points to an object or another list gives its name, 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 may be replaced by a token's value.
• Nothing found. If there's no list with the List Name, or no entry matches, the response is null. The status is 200, whatever Http code says, and Allow JSONP isn't applied. To return 404 instead, check first, for example with a condition on [CustomerList:Count] if the list action creates it, and use Raw Response.

Criteria

• The first entry where, for every criteria row, the Property value equals the Value is returned. Other entries are ignored.
• The Value can contain tokens, for example [id]. The comparison is exact and case-sensitive, and it's made on the value as text. Jane doesn't match jane.
• The Property name isn't case-sensitive.
• The property must exist. If an entry doesn't have a property named in the criteria, the action fails. This is different from Existing List as JSON, which keeps such entries.
• With no criteria, the first entry of the list is returned.

Considerations

• APIs only. The action is only available in API methods.
• 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. 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.
• Filter early. The action that creates the list loads all its rows, even if only one is returned. For large tables, select the single row in the query instead, for example with WHERE CustomerId = @id, and leave Criteria empty.

Examples

tip

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

1. Return the customer with a given ID

This action returns the entry of CustomerList whose CustomerId equals the id input of the API method.

{
    "Title": "Existing Object as JSON",
    "ActionType": "JsonEntity",
    "Description": "Return the requested customer",
    "Parameters": {
        "EntityName": "CustomerList",
        "HttpCode": "200",
        "Criteria": [
            {
                "name": "CustomerId",
                "value": "[id]"
            }
        ],
        "Headers": [],
        "AllowJsonp": false
    }
}

Revised 09/27/2026