Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

Update Customer

  • REST Method: PUT
  • URL: https://api.helpscout.net/v1/customers/{id}.json
  • Content-Type: application/json

When updating a customer, you can either pass the entire customer, or pass only the fields that need to be updated. On objects that have an id (such as socialProfiles, emails, phones, chats, websites), data that includes an id will be updated. Data not containing an id (or an id that evaluates to false—such as zero, false and/or null) will be created. To remove an entry, prefix its id with a minus sign (e.g. -1).


Name Type Required Default Notes
customer Customer Y   The body of the request (see example below).
reload boolean N false Set this request parameter to true to return the customer in the response.
    "firstName": "Vernon",
    "lastName": "Bear",
    "organization": "Acme, Inc",
    "jobTitle": "CEO and Co-Founder",
    "background": "I've worked with Vernon before and he's really great.",
    "address": {
        "id": 1234,
        "lines": [
            "123 West Main St",
            "Suite 123"
        "city": "Dallas",
        "state": "TX",
        "postcalCode": "74206",
        "country": "US",
        "createdAt": "2012-07-23T12:34:12Z"
        "modifiedAt": "2012-07-24T20:18:33Z"
    "socialProfiles": [
            "id": 1234,
            "value": "https://twitter.com/helpscout",
            "type": "twitter"
        {... social profile object ...}
    "emails": [{
            "id": -1234, // delete this email (prefixed with minus sign)
            "value": "vbear@mywork.com",
            "location": "work"
        {... email object ...}
    "phones": [{
            "id": 1234,
            "value": "222-333-4444",
            "location": "home"
        {... phone object ...}
    "chats": [{
            "id": 1234,
            "value": "jsprout",
            "type": "aim"
        {... chat object ...}
    "websites": [{
            "id": 1234,
            "value": "http://www.somewhere.com"
        {... website object ...}

Accepted Fields

Name Type Required Default Notes
firstName string Y    
lastName string Y    
emails Collection Y   Collection of CustomerEmail objects. At least one email address is required.
organization string N    
jobTitle string N    
background string N    
address CustomerAddress N    
socialProfiles Collection N   Collection of CustomerSocialProfile objects.
phones Collection N   Collection of CustomerPhone objects.
chats Collection N   Collection of CustomerChat objects.
websites Collection N   Collection of CustomerWebsite objects.


Response Name Type Notes
Header Status Integer 201
Header Location String https://api.helpscout.net/v1/customer/{id}.json
Status: 200 OK