Create Customer

Request

POST /v2/customers HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json; charset=UTF-8

{
  "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
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 have to be first defined in the web application. The expected format is "slug" : value pairs:

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 pulled via List Properties Definitions "556cca5f-1afc-48ef-8323-b88b55808404" 
{
 ...
 "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 2021