Search Customers (v3)

Requires the Access the contacts and companies directory permission, which Account Owners can turn off per role or per user.

Search customers with a query that combines several conditions, or looks up a list of email addresses or phone numbers in one request.

Use this endpoint only for filters that the typed parameters of List Customers (v3) cannot express; see Choosing between List and Search.

Request

GET /v3/customers/search?query=email%3A%28%22john%40appleseed.com%22%20OR%20%22jane%40appleseed.com%22%29 HTTP/1.1
Authorization: Bearer oauth_token

The whole search is expressed in the query parameter. It searches specific fields of the customer (field:value) and combines those conditions with the boolean operators AND and OR, grouped with parentheses; see Query syntax.


curl "https://api.helpscout.net/v3/customers/search?query=email:(john%40appleseed.com%20OR%20jane%40appleseed.com)"

Customers are sorted by creation date (createdAt) from newest to oldest using the customer id as tiebreaker. A request with invalid parameters, or a query that uses an unsupported field or construct, is rejected with a 400 Bad Request.

URL Parameters

Parameter Type Examples Description
query string query=email:("john@appleseed.com" OR "jane@appleseed.com")
query=phone:"+15555550123" OR background:"VIP"
 Search query: field clauses (field:value; quote a value that contains spaces) combined with uppercase AND, OR and parentheses. At most 500 characters. The only filter on this endpoint - the typed list filters are not accepted alongside it.

See Query syntax and Supported fields
cursor string cursor=eyJpZCI6MTIzfQ==
 Cursor for pagination. See Pagination

Start with List Customers (v3). Its typed parameters cover a lookup by a single email address or name, and customers created or modified since a date.

Use this endpoint when List’s typed parameters can’t express the filter: a list of email addresses or phone numbers to look up at once, a phone number, the customer’s background, OR across different fields, or a date range with both bounds.

Query syntax

A query is one or more clauses of the form field:value, with no space after the colon. Operators (AND, OR) are written in uppercase and surrounded by spaces; a lowercase and or or is read as a value without a field, so the query is rejected. Parentheses group clauses. Field names are case-insensitive.

  • Operators have no precedence: a query that mixes them without parentheses is grouped from the right, so firstName:John AND lastName:Appleseed OR lastName:Smith is firstName:John AND (lastName:Appleseed OR lastName:Smith). Use parentheses whenever a query mixes operators: (firstName:John OR firstName:Johnny) AND lastName:Appleseed.
  • Always write AND explicitly. Two clauses with no operator between them are joined with an AND that does not bind the way you might expect.
  • To match one of several values of the same field, group the values and separate them with OR: email:(a@acme.com OR b@acme.com) is the same as (email:a@acme.com OR email:b@acme.com). Don’t separate values with commas. The length limit below is the only cap on how many values a list can hold; it fits about 15 email addresses or 20 phone numbers.
  • Single-word values do not need quotes: firstName:John, email:john@appleseed.com. Quote a value that is more than one word: background:"VIP customer", phone:"+1 555 555 0123".
  • To search for a value that contains a character the syntax reserves (+ - ! ( ) { } [ ] ^ " ~ * ? : \ / & |), quote the value or escape the character with a backslash. A phone number that starts with + is the common case: phone:"+15555550123" or phone:\+15555550123.
  • Every value belongs to a field; a bare value such as john@appleseed.com on its own is not supported. Wildcards (firstName:Jo*) and the + / - clause modifiers are not supported either, and, unlike in Search Conversations (v3), neither is NOT.
  • A query can nest at most 20 levels deep; each group whose operator differs from the one around it adds a level.
  • A query is at most 500 characters, the same as Search Conversations (v3).
  • URL-encode the query; an HTTP client’s query-parameter encoding does this for you. When building the URL by hand, note that + must be encoded as %2B, or it is decoded as a space.

Supported fields

Only the following fields can be used in a query:

Field Value What it matches
firstName name Customer’s first name
lastName name Customer’s last name
email email address One of the customer’s email addresses (the whole address, case-insensitive)
phone phone number One of the customer’s phone numbers, compared on its digits only, so +1 (555) 555-0123 and 15555550123 match the same customer. The digits must match exactly, country code included: phone:"+15555550123" does not match a number stored as (555) 555-0123. A value with no digits, such as phone:"n/a", matches no customers
background word or phrase Customer’s background notes contain the whole word or phrase, case-insensitive; background:"VI" does not match “VIP customer”
createdAt date range Creation date within the range
modifiedAt date range Last-modified date within the range

Date fields (createdAt, modifiedAt) take an inclusive range, [lower TO upper]; exclusive {} bounds are not supported, and no other field takes a range. Each bound is a full UTC timestamp such as 2024-02-27T00:00:00Z. The lower bound is required; the upper bound can be * for an open end: [2024-02-27T00:00:00Z TO *] is everything from that timestamp onwards.

Examples

The queries are shown unencoded for readability; URL-encode them when sending the request.

Example What it does
query=email:(john@appleseed.com OR jane@appleseed.com) Customers with either email address
query=phone:("+15555550123" OR "+15555550124") Customers with either phone number
query=phone:"+15555550123" Customers with that phone number
query=background:VIP Customers whose background notes mention “VIP”
query=(firstName:John OR lastName:Appleseed) First name “John” or last name “Appleseed”
query=createdAt:[2024-01-01T00:00:00Z TO 2024-01-31T23:59:59Z] Customers created in January 2024
query=(lastName:Appleseed AND modifiedAt:[2024-02-27T00:00:00Z TO *]) Last name “Appleseed”, modified since 2024-02-27

Pagination

This endpoint uses cursor-based pagination. Follow the next link in the response to load the next page of results.

  • The response _links contains self, first, and, unless this is the last page, next.
  • Every link carries the query, so to page forward, request the URL in _links.next.href unchanged. Alternatively, repeat the same query and pass the link’s cursor value in the cursor parameter.
  • When _links.next is absent, there are no more results.
  • If a cursor is rejected, restart from the first page without one.
  • Each page holds up to 50 customers; the page size can’t be changed.
  • There are no last or prev links, and no page object.

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_embedded" : {
    "customers" : [ {
      "_links" : {
        "address" : {
          "href" : "..."
        },
        "chats" : {
          "href" : "..."
        },
        "emails" : {
          "href" : "..."
        },
        "phones" : {
          "href" : "..."
        },
        "social-profiles" : {
          "href" : "..."
        },
        "websites" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        }
      },
      "id" : 100,
      "firstName" : "Vernon",
      "lastName" : "Bear",
      "gender" : "Male",
      "jobTitle" : "CEO and Co-Founder",
      "location" : "Greater Dallas/FT Worth Area",
      "organization" : "Acme, Inc",
      "organizationId" : 35,
      "photoType" : "twitter",
      "photoUrl" : "http://twitter.com/img/some-avatar.jpg",
      "age" : "30-35",
      "conversationCount" : 10,
      "createdAt" : "2012-07-23T12:34:12Z",
      "updatedAt" : "2012-07-24T20:18:33Z",
      "background" : "I've worked with Vernon before and he's really great.",
      "draft" : false,
      "_embedded" : {
        "emails" : [ ],
        "phones" : [ ],
        "chats" : [ ],
        "social_profiles" : [ ],
        "websites" : [ ],
        "properties" : [ ]
      }
    }, {
      "_links" : {
        "address" : {
          "href" : "..."
        },
        "chats" : {
          "href" : "..."
        },
        "emails" : {
          "href" : "..."
        },
        "phones" : {
          "href" : "..."
        },
        "social-profiles" : {
          "href" : "..."
        },
        "websites" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        }
      },
      "id" : 101,
      "firstName" : "Vernon",
      "lastName" : "Bear",
      "gender" : "Male",
      "jobTitle" : "CEO and Co-Founder",
      "location" : "Greater Dallas/FT Worth Area",
      "organization" : "Acme, Inc",
      "organizationId" : 35,
      "photoType" : "twitter",
      "photoUrl" : "http://twitter.com/img/some-avatar.jpg",
      "age" : "30-35",
      "conversationCount" : 10,
      "createdAt" : "2012-07-23T12:34:12Z",
      "updatedAt" : "2012-07-24T20:18:33Z",
      "background" : "I've worked with Vernon before and he's really great.",
      "draft" : false,
      "_embedded" : {
        "emails" : [ ],
        "phones" : [ ],
        "chats" : [ ],
        "social_profiles" : [ ],
        "websites" : [ ],
        "properties" : [ ]
      }
    } ]
  },
  "_links" : {
    "next" : {
      "href" : "..."
    },
    "self" : {
      "href" : "..."
    },
    "first" : {
      "href" : "..."
    }
  }
}

Response fields

Path Type Description
_embedded.customers Array Array of Customer objects
_links.self Object Link to the current page
_links.first Object Link to the first page
_links.next Object Link to the next page (absent on the last page)
↑Back to top