# Customers

Customers are the people who have contacted your support center in some way. For example, a customer is created when a conversation is started, and the email used in the conversation does not belong to any customer in the account.

Customers allow you to have good context on who you are talking with, attach customer-level notes, details, etc.

# The customer object

id integer

The system-generated ID of the customer
name string

The full name of the customer based on first_name and last_name. If first_name and last_name are empty, an email associated with the customer will be shown.
initials string

The initials of the customer based on the first letter of the first_name and last_name.
first_name string

The first name of the customer.
last_name string

The last name of the customer.
company string

The name of the company the customer works for.
account_id integer

The account id where the customer belongs to.
avatar string

The URL of the avatar image.
emails array

The emails associated with the customer.
phones array

The phone numbers associated with the customer.
websites array

The websites associated with the customer.
stats object

The stats of the customer. This attribute is only included when retrieving a single customer.
created_at string

The timestamp when the customer was created.
updated_at string

The timestamp when the customer was last updated.

# The customer object

{
  "id": 1,
  "name": "Jane Doe",
  "initials": "JD",
  "first_name": "Jane",
  "last_name": "Doe",
  "company": null,
  "account_id": 1,
  "avatar": null,
  "emails": [
    {
      "id": 1,
      "email": "jane@example.org"
    }
  ],
  "phones": [
    {
      "id": 1,
      "phone": "123 123 1234"
    }
  ],
  "websites": [
    {
      "id": 1,
      "website": "https://www.example.org/"
    }
  ],
  "stats": {
    "conversations": {
      "total": 2,
      "posted": 0,
      "pending": 0,
      "closed": 2,
      "email_channel": 2
    }
  },
  "updated_at": "2019-04-25T17:51:31+00:00",
  "created_at": "2019-04-25T17:51:31+00:00"
}

# Create a customer

first_name string required

The first name of the customer.
last_name string optional

The last name of the customer.
company string

The name of the company the customer works for.
emails array optional

The emails associated with the customer. Limited to 15 emails.
phones array optional

The phone numbers associated with the customer. Limited to 25 phones.
websites array optional

The websites associated with the customer. Limited to 150 websites.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/customers \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d first_name="Jane" \
  -d last_name="Doe" \
  -d emails[0][email]="jane@example.org" \
  -d phones[0][phone]="123 123 1234" \
  -d websites[0][website]="https://www.example.org/"

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "initials": "JD",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": null,
    "account_id": 1,
    "avatar": null,
    "emails": [
      {
        "id": 1,
        "email": "jane@example.org"
      }
    ],
    "phones": [
      {
        "id": 1,
        "phone": "123 123 1234"
      }
    ],
    "websites": [
      {
        "id": 1,
        "website": "https://www.example.org/"
      }
    ],
    "stats": {
      "conversations": {
        "total": 0,
        "posted": 0,
        "pending": 0,
        "closed": 0,
        "email_channel": 0
      }
    },
    "updated_at": "2019-04-25T17:51:31+00:00",
    "created_at": "2019-04-25T17:51:31+00:00"
  }
}

# Retrieve a customer

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/customers/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "initials": "JD",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": null,
    "account_id": 1,
    "avatar": null,
    "emails": [
      {
        "id": 1,
        "email": "jane@example.org"
      }
    ],
    "phones": [
      {
        "id": 1,
        "phone": "123 123 1234"
      }
    ],
    "websites": [
      {
        "id": 1,
        "website": "https://www.example.org/"
      }
    ],
    "stats": {
      "conversations": {
        "total": 2,
        "posted": 0,
        "pending": 0,
        "closed": 2,
        "email_channel": 2
      }
    },
    "updated_at": "2019-04-25T17:51:31+00:00",
    "created_at": "2019-04-25T17:51:31+00:00"
  }
}

# Update a customer

first_name string required

The first name of the customer.
last_name string optional

The last name of the customer.
company string

The name of the company the customer works for.
emails array optional

The emails associated with the customer. Email will be created if it is missing the id attribute or if the given id value does not exists, otherwise, it is updated. Limited to 15 emails.
phones array optional

The phone numbers associated with the customer. Phone will be created if it is missing the id attribute or if the given id value does not exists, otherwise, it is updated. Limited to 25 phones.
websites array optional

The websites associated with the customer. Website will be created if it is missing the id attribute or if the given id value does not exists, otherwise, it is updated. Limited to 150 websites.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/customers/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d first_name="Jane" \
  -d last_name="Doe" \
  -d emails[0][id]=1 \
  -d emails[0][email]="janedoe@example.org"

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "initials": "JD",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": null,
    "account_id": 1,
    "avatar": null,
    "emails": [
      {
        "id": 1,
        "email": "janedoe@example.org"
      }
    ],
    "phones": [
      {
        "id": 1,
        "phone": "123 123 1234"
      }
    ],
    "websites": [
      {
        "id": 1,
        "website": "https://www.example.org/"
      }
    ],
    "updated_at": "2019-04-25T17:51:31+00:00",
    "created_at": "2019-04-25T17:51:31+00:00"
  }
}

# Delete a customer

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/customers/1 \
  --request DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

# List all customers

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/customers \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": [
    {
      "id": 1,
      "name": "Jane Doe",
      "initials": "JD",
      "first_name": "Jane",
      "last_name": "Doe",
      "company": null,
      "account_id": 1,
      "avatar": null,
      "emails": [
        {
          "id": 1,
          "email": "janedoe@example.org"
        }
      ],
      "phones": [
        {
          "id": 1,
          "phone": "123 123 1234"
        }
      ],
      "websites": [
        {
          "id": 1,
          "website": "https://www.example.org/"
        }
      ],
      "updated_at": "2019-04-25T17:51:31+00:00",
      "created_at": "2019-04-25T17:51:31+00:00"
    },
    {...}
  ]
}

← Mailboxes Customer PGP Public Keys →

# Customers

# The customer object

id integer

name string

initials string

first_name string

last_name string

company string

account_id integer

avatar string

emails array

phones array

websites array

stats object

created_at string

updated_at string

# The customer object

# Create a customer

first_name string required

last_name string optional

company string

emails array optional

phones array optional

websites array optional

# Sample request

# Sample successful response

# Retrieve a customer

# Sample request

# Sample successful response

# Update a customer

first_name string required

last_name string optional

company string

emails array optional

phones array optional

websites array optional

# Sample request

# Sample successful response

# Delete a customer

# Sample request

# List all customers

# Sample request

# Sample successful response