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 Type Examples Description
page number page=1
 Page number
mailbox number mailbox=85
 Filters customers from a specific mailbox
firstName string firstName=vernon
 Filters customers by first name
lastName string lastName=bear
 Filters customers by last name
modifiedSince date modifiedSince=2018-05-04T12:00:03Z
 Returns only customers that were modified after this date
sortField enumeration sortField=firstName
 Sorts the result by specified field:
score - default
firstName
lastName
modifiedAt
sortOrder enumeration sortOrder=desc
 sort order, either desc or asc, default is desc
query special query=(firstName:"John")
 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 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" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Response fields

Path Type Description
_embedded.customers Array Array of Customer objects
↑Back to top
© Help Scout 2024