Contacts

Contacts are the people in your CRM and their associated company, communication details, and metadata.

Default sort: weight descending. When you omit order_by, contacts return in Action Stream priority order (the same order the OnePageCRM app uses).

Fields

Legend: F filterable, S sortable, A aggregatable, G groupable.

Notes

• Virtual fields (status, lead_source) are display labels resolved from their underlying _id field at query time. You cannot select, filter, or sort by them directly; use the _id field instead.
• tags uses bare-string equality for single-tag membership ({"tags": "VIP"}) and in for multi-tag overlap ({"tags": {"in": ["VIP", "Hot"]}}). Grouping by tags gives a per-tag breakdown: each tag is its own bucket, so a contact tagged both VIP and Hot is counted under each. count() per tag is exact; summing an unrelated field double-counts multi-tag contacts.
• starred is per-user. The value reflects whether the calling user has starred the contact, not whether anyone has.
• emails, phones, urls are arrays of objects. Filter using dotted subfields:
  • emails.address, emails.type (work, home, other)
  • phones.number, phones.type (work, mobile, home, direct, fax, other)
  • urls.url, urls.type (website, blog, twitter, linkedin, facebook, instagram, xing, other)
• Lookups: company (via company_id). Pull the linked company record’s fields inline as company.<field> — for example company.name, company.city, or company.country_code — in select, where, and order_by. See Concepts › Lookups.
• company_name vs the company lookup. company_name is text stored on the contact and is set even when no company record is linked; company.<field> reads the linked record. A contact with a company_name but no company_id returns null for every company.<field>.
• Custom fields are queryable by name as custom_fields.<name> in select, where, and order_by; select custom_fields.* (or *) to return all of them. Filterability and sortability depend on the field’s type. Numeric custom fields can also be aggregated ({ "sum": ["custom_fields.<name>"] }), and min/max work on date custom fields. group_by and distinct on custom fields are not supported: group by a top-level field and filter on the custom field in where instead. Use describe to discover an account’s custom-field names and types.

Example queries

Open leads owned by me, top of stream:

{
  "from": "contacts",
  "where": { "owner_id": "ME()", "status_id": "lead" },
  "limit": 25
}

Contacts I’ve starred:

{
  "from": "contacts",
  "where": { "starred": true }
}

Contacts whose linked company is in Ireland, with the company’s city:

{
  "from": "contacts",
  "select": ["first_name", "last_name", "company_name", "company.city"],
  "where": { "company.country_code": "IE" },
  "order_by": [{ "company.name": "asc" }]
}

Contacts at an Irish phone number, with no activity in the last 30 days:

{
  "from": "contacts",
  "where": {
    "phones.number": { "like": "+353%" },
    "last_activity_date": { "<": { "DAYS_AGO": [30] } }
  }
}

Contacts by country:

{
  "from": "contacts",
  "select": ["country_code", "count()"],
  "where": { "country_code": { "is not": null } },
  "group_by": ["country_code"]
}