Discussions

In the v2 platform API, is there a way to retrieve multiple records with specific connected objects' fields populated through a single API call?

Related to my previous question RE: filtering on a record's updatedAt, we'd like to reduce the number of API calls needed to get comprehensive data - e.g., all a Customer's locations, addresses, and contacts - for comparison in other systems.

Reading through the retrieve record endpoint , there is a paths parameter to add connected objects (and their fields) to the response. This works as described for a single record. Is there a way to apply this to the list records endpoint?

It appears paths is recognized as a parameter the list records request body, though it is not described in the documentation.

e.g., if I send a non-array value, it responds with HTTP 400:

// request, POST -> /objects/search
{
    "boardId": "<customers board ID>",
    "paths": "abc",
    "offset": 0,
    "limit": 2
}

// response, HTTP 400: 
{
    "message": [
        "paths must be an array"
    ],
    "error": "Bad Request",
    "statusCode": 400
}

If I change it to an array of strings, the request succeeds, but does not appear to include the connected objects' fields at any depth:

// request, POST -> /objects/search
{
    "boardId": "<customers board ID>",
    "paths": ["contacts", "contacts.firstName", "locations.address.address1"],
    "offset": 0,
    "limit": 2
}

// response, HTTP 200, redacted
// includes customers, and basic info for contacts and locations->address, but not fields set in request paths
{
    "total": 191,
    "results": [
        {
            "id": "...",
            "objectKey": "customer",
            "orgId": "...",
            "source": "manual",
            "createdAt": "2024-12-27T14:07:10.984Z",
						// snipped
            "fullId": "...",
            "name": "...",
            "locations": [
                {
                    "id": "...",
                    "objectKey": "location",
                    "orgId": "...",
                    "source": "manual",
                    "createdAt": "2024-12-27T14:07:10.984Z",
                    "address": {
                        "id": "...",
                        "objectKey": "address",
                        "orgId": "...",
                        "source": "manual",
                        "createdAt": "2024-12-27T14:07:10.984Z",
                        "widgets": [],
                        "name": "..."
                        // locations.address.address1 not added
                    },
                    "fullId": "..."
                }
            ],
            // ...
            // "contacts" array not in response at all
        },

I understand connecting related objects for an arbitrary number of records is expensive, for processing amount of data, etc, but I'd like to confirm whether or not it is possible, presently, with the v2 API.

As confirmed earlier, the single record endpoint does return connected objects' fields listed in paths, so our workaround is to get a list of record IDs, then use the single record endpoint to get details for each top-level record from there, but our intent is to reduce overhead, respect rate limits, and limit data retrieved as best we can.