List Customers (v3)

Request

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

Request parameters can be used to filter customers. All parameters are joined by the AND operator.


curl https://api.helpscout.net/v3/customers?firstName=Amanda

Customers are sorted by creation date (createdAt) from newest to oldest using the customer id as tiebreaker.

URL Parameters

Parameter Type Examples Description
firstName string firstName=vernon
 Filters customers by first name
lastName string lastName=bear
 Filters customers by last name
email string email=john@appleseed.com
 Filters customers by email
createdSince date createdSince=2018-05-04T12:00:03Z
 Returns only customers that were created after this date
modifiedSince date modifiedSince=2018-05-04T12:00:03Z
 Returns only customers that were modified after this date
query special query=(firstName:"John")
 Advanced search query
cursor string cursor=eyJpZCI6MTIzfQ==
 Cursor for pagination

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 containing “john@appleseed.com”
query=(email:("john@appleseed.com" OR "johnappleseed@gmail.com")) Searches for customers who have an email containing “john@appleseed.com” or “johnappleseed@gmail.com”

Modified Since

Example What it does
query=modifiedAt:[2013-11-20T00:00:00Z TO *] Searches for customers who have been modified since 2013-11-20

Response

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

{
  "_embedded" : {
    "customers" : [ {
      "id" : 1,
      "firstName" : "Vernon",
      "lastName" : "Bear",
      "gender" : "Male",
      "jobTitle" : "CEO and Co-Founder",
      "location" : "Greater Dallas/FT Worth Area",
      "organization" : "Acme, Inc",
      "photoType" : "twitter",
      "photoUrl" : "http://twitter.com/img/some-avatar.jpg",
      "age" : "30-35",
      "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" : 2,
      "firstName" : "Vernon",
      "lastName" : "Bear",
      "gender" : "Male",
      "jobTitle" : "CEO and Co-Founder",
      "location" : "Greater Dallas/FT Worth Area",
      "organization" : "Acme, Inc",
      "photoType" : "twitter",
      "photoUrl" : "http://twitter.com/img/some-avatar.jpg",
      "age" : "30-35",
      "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" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "first" : {
      "href" : "..."
    },
    "next" : {
      "href" : "..."
    }
  }
}

Response fields

Path Type Description
_embedded.customers Array Array of Customer objects
_links.self Object Link to current request
_links.first Object Link to first page
_links.next Object Link to next page (only present when more data is available)
↑Back to top