# Attio People Query Reference

## Filter Syntax

Filters use attribute slugs with condition operators.

**Basic filter structure:**

```json
{
  "filter": {
    "attribute_slug": {
      "condition": "value"
    }
  }
}
```

## Common Conditions

**Text/String attributes:**

- `{"$eq": "exact match"}` — equals
- `{"$contains": "substring"}` — contains text
- `{"$not_empty": true}` — has a value
- `{"$is_empty": true}` — is empty/null

**Email addresses:**

```json
{"email_addresses": {"$contains": "@company.com"}}
```

**Select/Status attributes:**

```json
{"status": {"$eq": "active"}}
```

**Record references (linked companies):**

```json
{"company": {"$contains": "record_id_here"}}
```

**Date attributes:**

- `{"$lt": "2024-01-01"}` — before date
- `{"$gt": "2024-01-01"}` — after date
- `{"$gte": "2024-01-01"}` — on or after
- `{"$lte": "2024-01-01"}` — on or before

## Compound Filters

**AND (all conditions must match):**

```json
{
  "filter": {
    "$and": [
      {"email_addresses": {"$not_empty": true}},
      {"job_title": {"$contains": "Engineer"}}
    ]
  }
}
```

**OR (any condition matches):**

```json
{
  "filter": {
    "$or": [
      {"job_title": {"$contains": "CEO"}},
      {"job_title": {"$contains": "Founder"}}
    ]
  }
}
```

## Sorts

```json
{
  "sorts": [
    {"attribute": "name", "direction": "asc"},
    {"attribute": "created_at", "direction": "desc"}
  ]
}
```

Directions: `asc` (ascending), `desc` (descending)

## Standard People Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `name` | text | Full name |
| `email_addresses` | email | Email addresses (array) |
| `phone_numbers` | phone | Phone numbers (array) |
| `job_title` | text | Job title |
| `company` | record-reference | Linked company record |
| `primary_location` | location | Location with city, region, country |
| `description` | text | Notes/description |
| `created_at` | timestamp | Record creation time |

## Example Queries

**Find people at a specific company:**

```json
{
  "filter": {"company": {"$contains": "company_record_id"}}
}
```

**Find people with email addresses:**

```json
{
  "filter": {"email_addresses": {"$not_empty": true}}
}
```

**Find engineers, sorted by name:**

```json
{
  "filter": {"job_title": {"$contains": "Engineer"}},
  "sorts": [{"attribute": "name", "direction": "asc"}]
}
```

**Find people added recently:**

```json
{
  "filter": {"created_at": {"$gt": "2024-01-01"}},
  "sorts": [{"attribute": "created_at", "direction": "desc"}]
}
```

## Pagination

The API returns up to 100 records per request. Use `offset` for pagination:

- First page: no offset
- Next page: use `next_page_offset` from response

The code bullet handles pagination automatically up to `maxResults`.