Related Records

The include query parameter embeds related records directly inside the data object of a Get a record response. This avoids a second round-trip when you need associated accounts, contacts, signals, or projects alongside a primary record.

Pattern

GET /data/{dataset}/{id}?include=<key>

include is repeatable: add it once per key you want embedded.

Multiple includes

GET /data/projects/{id}?include=accounts&include=contacts&include=signals

Include keys by dataset

Dataset	Key	Embeds	Shape
accounts	projects	projects associated with the account	array
accounts	contacts	contacts at the account	array
accounts	signals	signals on the account’s projects	array
contacts	account	the contact’s parent account	object
contacts	projects	projects the contact appears on	array
projects	accounts	accounts on the project	array
projects	contacts	contacts on the project	array
projects	signals	timeline signals for the project	array
signals	project	the project the signal belongs to	object
signals	accounts	accounts associated with the signal	array

To-one keys (contacts.account, signals.project) embed a single object, or null when there is no related record. To-many keys embed an array, which is empty ([]) when there are no related records.

Note

A detail fetch always costs 1 credit regardless of how many include keys are used.

Example

cURL

Fetch project with accounts and contacts

curl "https://api.parcelengineering.com/api/v1/data/projects/8a1f3c2e-0000-0000-0000-000000000001?include=accounts&include=contacts" \
  -H "Authorization: Bearer pcl_your_api_key"

JavaScript

Fetch project with accounts and contacts

const id = '8a1f3c2e-0000-0000-0000-000000000001';
const params = new URLSearchParams([
  ['include', 'accounts'],
  ['include', 'contacts'],
]);

const response = await fetch(
  `https://api.parcelengineering.com/api/v1/data/projects/${id}?${params}`,
  {
    headers: { 'Authorization': 'Bearer pcl_your_api_key' },
  }
);

const { data, metadata } = await response.json();
// data.accounts -> array of accounts
// data.contacts -> array of contacts

Response (trimmed)

{
  "data": {
    "id": "8a1f3c2e-0000-0000-0000-000000000001",
    "name": "40 Trinity Place",
    "city": "Boston",
    "stage": "approved",
    "residential_units": 120,
    "last_signal_at": "2025-11-04",
    "accounts": [
      {
        "id": "8a1f3c2e-0000-0000-0000-000000000010",
        "name": "Acme Development LLC",
        "account_types": ["developer"],
        "city": "Boston",
        "state": "MA"
      },
      {
        "id": "8a1f3c2e-0000-0000-0000-000000000011",
        "name": "Blueprint Architecture",
        "account_types": ["architect"],
        "city": "Boston",
        "state": "MA"
      }
    ],
    "contacts": [
      {
        "id": "8a1f3c2e-0000-0000-0000-000000000020",
        "name": "Jane Smith",
        "title": "Project Manager",
        "email": "jane@acmedev.com"
      }
    ]
  },
  "metadata": {
    "credits": 1
  }
}

Using includes with search

include is only available on the Get a record endpoint (GET /data/{dataset}/{id}). It is not supported on POST /data/{dataset}/search. To retrieve related records for a set of search results, fetch each record individually by ID after searching.