List Customers

Request

GET /v2/customers HTTP/1.1
Authorization: Bearer oauth_token

Request parameters can be used to filter customers. All parameters are joined by the AND operator. If you want customers with first name Amanda in a specific mailbox, call:


curl https://api.helpscout.net/v2/customers?mailbox=123&firstName=Amanda

Customers are by default sorted by createdAt (from newest to oldest). This is equivalent to ?sortField=createdAt&sortOrder=desc.

URL Parameters

Parameter Description
page Page number
mailbox Filters customers from a specific mailbox
firstName Filters customers by first name
lastName Filters customers by last name
modifiedSince Returns only customers that were modified after this date
sortField Sorts the result by specified field:
score - default
firstName
lastName
modifiedAt
sortOrder sort order, either desc or asc, default is desc
query advanced search query

Query

Name

Example What it does
query=(firstName:"John") Searches for customers who have a first name of “John”
query=(lastName:"Appleseed") Searches for customers who have a last name of “Appleseed”
query=(firstName:"John" OR firstName:"Johnny") Searches for customers who have a first name of either “John” or “Johnny”
query=(firstName:"John" AND lastName:"Appleseed") Searches for customers who have a first name of “John” and a last name of “Appleseed”

Email

Example What it does
query=(email:"john@appleseed.com") Searches for customers who have an email of “john@appleseed.com”
query=(email:("john@appleseed.com" OR "johnappleseed@gmail.com") Searches for customers who have an email of “john@appleseed.com” or “johnappleseed@gmail.com”
query=(emailDomain:("gmail.com") Searches for customers who have emails with gmail.com hostname

Modified Since

Example What it does
query=(modifiedSince:"2013-11-20T00:00:00Z") Searches for customers who have been modified since 2013-11-20

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded" : {
    "customers" : [ {
      "id" : 1,
      "firstName" : "Vernon",
      "createdAt" : "1970-01-01T00:00:00Z",
      "_links" : {
        "address" : {
          "href" : "..."
        },
        "chats" : {
          "href" : "..."
        },
        "emails" : {
          "href" : "..."
        },
        "phones" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        },
        "social-profiles" : {
          "href" : "..."
        },
        "websites" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 2,
      "firstName" : "Vernon",
      "createdAt" : "1970-01-01T00:00:00Z",
      "_links" : {
        "address" : {
          "href" : "..."
        },
        "chats" : {
          "href" : "..."
        },
        "emails" : {
          "href" : "..."
        },
        "phones" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        },
        "social-profiles" : {
          "href" : "..."
        },
        "websites" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    },
    "self" : {
      "href" : "..."
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Response fields

Path Type Description
_embedded.customers Array Array of Customer objects