Data API

Contacts

Search and retrieve people associated with accounts and projects in Parcel, including architects, engineers, project managers, and other team members.

Contacts are people associated with accounts or projects tracked in Parcel: architects, engineers, project managers, business owners, and other team members. Each contact links to a parent account and may appear across multiple projects in different roles.

Fields

Field	Type	Notes
`id`	`uuid`	Unique contact identifier
`account_id`	`uuid`	Parent account
`name`	`string`	Full name
`title`	`string \| null`	Job title
`email`	`string \| null`	Email address
`phone`	`string \| null`	Phone number
`linkedin_url`	`string \| null`	LinkedIn profile URL
`enrichment_status`	`string`	Enrichment state for this record. See Contact enrichment
`created_at`	`string`	ISO 8601 timestamp, first seen in Parcel
`updated_at`	`string`	ISO 8601 timestamp of last update
`projects_count`	`int`	Number of associated projects

Filters

Default sort: name asc

Top-level query performs fuzzy matching across contact name, title, email, phone, and associated account name.

Filter key	Type	Notes
`name`	field	Full or partial name. Supports fuzzy match
`title`	field	Job title. Supports fuzzy match
`email`	field	Exact or fuzzy email match
`account_id`	field	Filter to contacts at a specific account (UUID)

Sort keys: name, created_at

Range keys: none

Relational filters

Use relational filters to match contacts based on properties of their related records.

Key	Inner filter fields
`at_account`	`name`, `city`, `account_type`
`on_project`	`stage`, `primary_use`, `city`, `role`, `name`

Includes

Valid include keys for GET /data/contacts/{id}: account (to-one, embeds an object), projects.

Example: GET /data/contacts/<id>?include=account&include=projects

curl -X POST https://api.parcelengineering.com/api/v1/data/contacts/search \
  -H "Authorization: Bearer pcl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "on_project": {
        "city": { "value": "Boston" },
        "stage": { "value": "approved" }
      },
      "at_account": {
        "account_type": { "value": "architect" }
      }
    },
    "sort": { "field": "name", "order": "asc" },
    "limit": 10
  }'

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/data/contacts/search',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pcl_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filters: {
        on_project: {
          city: { value: 'Boston' },
          stage: { value: 'approved' },
        },
        at_account: {
          account_type: { value: 'architect' },
        },
      },
      sort: { field: 'name', order: 'asc' },
      limit: 10,
    }),
  }
);

const { data, metadata } = await response.json();

{
  "data": [
    {
      "id": "8a1f3c2e-0002-4b7d-9e5a-000000000002",
      "account_id": "8a1f3c2e-0001-4b7d-9e5a-000000000001",
      "name": "Jordan Lee",
      "title": "Principal Architect",
      "email": "jordan.lee@example-arch.com",
      "phone": "+16175550123",
      "linkedin_url": "https://www.linkedin.com/in/jordan-lee-arch",
      "enrichment_status": "enriched",
      "created_at": "2024-04-10T08:30:00Z",
      "updated_at": "2025-01-22T14:00:00Z",
      "projects_count": 5
    }
  ],
  "metadata": {
    "total": 83,
    "total_is_capped": false,
    "credits": 10
  }
}

The data array is trimmed to one record above; a full limit: 10 page returns 10 records and costs 10 credits (1 per record returned).