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

• Writing status_id or tags can change other contacts. If the contact belongs to a company with sync_status or sync_tags set, that write applies to every contact in the company, not just the one you addressed. Tags are replaced wholesale rather than merged, so the other contacts’ tags are overwritten. Check the flags on companies before writing either field.
• status and status_id are one field, the name and the id, and so are lead_source and lead_source_id: {"status": "Customer"} and {"status_id": "customer"} are the same filter. See Concepts › Names and ids for the rules. If two statuses share a display name the name covers both: filtering returns contacts on either, grouping merges them, and a write keeps whichever id the contact already has.
• 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. Writing true or false stars or unstars it for that user alone.
• sales_cycle_closed is per-user too, and read-only here. It is true when the calling user closed the sales cycle with the contact, which also deleted that user’s open next actions on it. So a contact with no next action is either closed (true) or stalled (false). A colleague may still have the cycle open. Assigning a new action reopens it.
• pending_deal is true when the contact has at least one deal still pending. Won and lost deals do not count, so false does not mean the contact has never had a deal — it means none are open right now. It is a flag, not a figure: for values, query deals with contact_id.
• 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. Always name a subfield: company on its own is a lookup, not a field, and selecting it bare is rejected. 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 works on custom fields whose type supports it (check describe); distinct does not — group by the field 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 }
}

My customers, by name rather than by id:

{
  "from": "contacts",
  "select": ["first_name", "last_name", "status", "lead_source"],
  "where": { "status": "Customer", "owner_id": "ME()" }
}

Contacts I have not finished with that mention golf:

{
  "from": "contacts",
  "where": {
    "owner_id": "ME()",
    "sales_cycle_closed": false,
    "background": { "contains": "golf" }
  }
}

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"]
}