/v1/contacts

Fetch contacts in pages.

Searching

Pass a q query parameter to restrict the results to contacts that match a query expressed in Apptoto's contact search language. Examples:

• q=fred -- bare term, matches name, email, or phone
• q=name:fred -- contains-match against the name
• [email protected] -- exact email match (case-insensitive)
• q=phone=+14155551234 -- exact phone match (numbers are normalized before comparison)
• q=(name:fred OR name:smith) AND zip:97201 -- boolean combination
• q=custom.referral_source:website -- match a custom field

Custom fields defined under Settings > Field Settings in the portal can be referenced by their bare name (e.g. q=referral_source:website), and number / date typed fields support numeric and date comparisons.

See the Contact Search Syntax article for the full operator and field reference.

Pagination (page, page_size) and address_book_id are applied on top of q.

Example Result:

{
  contacts: [
    {
      id: 1,
      external_id: "yourid",
      name: "Fred Smith",
      first_name: "Fred",
      last_name: "Smith",
      zip: "97701",
      address_book_id: 123,
      address_book_name: "Apptoto Address Book",
      writable: true,
      notes: "Long string of notes",
      deleted: false,
      phone_numbers: [
        {
          id: 3,
          number: "650-555-1212",
          normalized: "+16505551212",
          type: "mobile",
          is_primary: true
        }
      ],
      email_addresses: [
        {
          id: 4,
          address: "[email protected]",
          type: "work"
        }
      ],
      custom_data: {
        field_1: "vip"
      }
    }
  ]
}

OAuth scope

Calls authenticated with an OAuth 2.0 bearer token must include the contacts:read scope. A token without it receives a 403 insufficient_scope response. HTTP Basic auth is not scope-gated.