Create Customer

Request

POST /v2/customers HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json

{
  "firstName" : "Vernon",
  "lastName" : "Bear",
  "photoUrl" : "https://api.helpscout.net/img/some-avatar.jpg",
  "photoType" : "twitter",
  "jobTitle" : "CEO and Co-Founder",
  "location" : "Greater Dallas/FT Worth Area",
  "background" : "I've worked with Vernon before and he's really great.",
  "age" : "30-35",
  "gender" : "Male",
  "organization" : "Acme, Inc",
  "emails" : [ {
    "type" : "work",
    "value" : "bear@acme.com"
  } ]
}

Request fields

Path Type Required Description
firstName String N First name of the customer. When defined it must be between 1 and 40 characters.
lastName String N Last name of the customer. When defined it must be between 1 and 40 characters.
phone String N Optional phone number that will be used when creating a new customer
photoUrl String N URL of the customer’s photo. Max length 200 characters.
jobTitle String N Job title. Max length 60 characters.
photoType String N Type of photo. Accepted values are:
unknown
gravatar
twitter
facebook
googleprofile
googleplus
linkedin
instagram
background String N This is the Notes field from the user interface. Max length 200 characters.
location String N Location of the customer. Max length 60 characters.
organization String N Organization. Max length 60 characters.
gender String N Gender of this customer. Accepted values are:
male
female
unknown
age String N Customer’s age
emails Array N List of email entries, see Create Email for the object documentation
phones Array N List of phones entries, see Create Phone for the object documentation
chats Array N List of chat entries, see Create Chat Handle for the object documentation
socialProfiles Array N List of social profile entries, see Create Social Profile for the object documentation
websites Array N List of website entries, see Create Website for the object documentation
address Object N Customer’s address, see Create Address for the object documentation
properties Object N Customer properties

Customer properties

Field properties is used to populate customer property values. The properties must first be created either in the web application or via the Create Property Definitions Endpoint.

The expected format is "slug" : value pairs.

The slug must be unique within the company and have length between 1 and 100 characters. It may only contain alphanumeric characters, hyphens, and underscores. The slugs email, name, company and jobTitle are reserved.

The value format differs per property type:

Property type Format Example
number Integer (range of [-9223372036854775808, 9223372036854775807]) 5
text String (max of 255 characters) "green"
url Valid URL "google.com"
date Valid date (YYYY-MM-DD) "2019-01-02"
dropdown Valid dropdown option value, which can be either the option id or label pulled via List Properties Definitions "556cca5f-1afc-48ef-8323-b88b55808404" or "Tesla" 
{
 ...
 "properties" : [
    { "slug" : "car", "value" : "Tesla" },
    { "slug" : "favoriteCartoon", "value": "Tom and Jerry" }
  ]
}

Response

HTTP/1.1 201 Created
Resource-ID: 101
Location: https://api.helpscout.net/v2/customers/101
↑Back to top
© Help Scout 2025