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 5
text String "green"
bool Boolean - true or false true
url Valid URL "https://google.com"
date Valid date 2019-01-02
{
 ...
 "properties" : {
    "car" : "Tesla",
    "shoeSize" : 44
  }
}

Response

HTTP/1.1 201 Created
Resource-ID: 101
Location: https://api.helpscout.net/v2/customers/101
Keep-Alive: timeout=60
Connection: keep-alive