Create customer

Add a single customer to your account

Written by Konstantine

Updated 6 months ago

You can create a single customer with this method. To create a chat on behalf of that customer, please use the Create chat method.

➡️ Request

URL	https://api.helpcrunch.com/v1/customers
Method	POST
Headers	Authorization: Bearer <your_api_key>

When creating a customer you can specify all the existing data fields or a part of them in the body of your POST request. You can find all the available data fields in the Successful Response section below.

Read more about the authorization header here.

There are no required fields for this method, however, we do not recommend creating customers without any data specified. Name, email and userId are the preferred fields you should always send.

When you create a customer, HelpCrunch automatically creates an internal customer id for them. userId is not the internal HelpCrunch customer id, you can pass your own customer id there (e.g. from your CRM).

Request Body

{
  "name": "John Doe",
  "email": "[email protected]",
  "userId": "user_1234567890",
  "company": "Example Inc.",
  "phone": "+10233456781",
  "firstSeen": "1603885746",
  "source": "https://example.com",
  "locale": "uk",
  "notes": "Lorem ipsum",
  "tags": [
    {
      "name": "vip",
      "color": "#ff0000"
    }
  ],
  "customData": [
    {
      "property": "subscription_status",
      "value": "active"
    },
    {
      "property": "number_of_payments",
      "value": 15
    },
    {
      "property": "last_paid_amount",
      "value": 15.99
    },
    {
      "property": "last_payment_date",
      "value": "1603885746"
    },
    {
      "property": "last_invoice_url",
      "value": "https://example.com/invoice.html"
    },
    {
      "property": "last_payment_was_successful",
      "value": true
    }
  ]
}

Tips

All dates should be passed in the String (UNIX timestamp) format;
Locale filed should be passed as a string according to the ISO 639-1 standard;
Tag will be automatically created and added to your account if you pass a non-existing one. You can assign any CSS color to the tag. If you don't specify it, the default #c377e0 color will be applied.

To create the new customData attribute, go to Settings → Contacts → Custom attributes and click 'Add new attribute'.

✅ Successful Response

If your request has succeeded, you'll get a 201 Created success status code together with the following response body.

{
  "id": 542335,
  "name": "John Doe",
  "email": "[email protected]",
  "userId": "user_1234567890",
  "company": "Example Inc.",
  "phone": "+10233456781",
  "firstSeen": "1603885746",
  "lastSeen": "1603885746",
  "location": {
    "regionCode": "Kyyivs'ka Oblast",
    "countryCode": "UA",
    "city": "Kyiv"
  },
  "device": {
    "id": 542335,
    "ip": "192.168.1.1",
    "timezone": "Europe/Kiev",
    "platform": "desktop",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36"
  },
  "unsubscribed": false,
  "blocked": false,
  "source": "https://example.com",
  "referer": "https://example.com",
  "lastPage": "https://example.com",
  "locale": "uk",
  "createdFrom": "telegram",
  "integrationId": "465847687",
  "notes": "Lorem ipsum",
  "tags": [
    {
      "name": "vip",
      "color": "#ff0000"
    }
  ],
  "customData": {
    "subscription_status": "active",
    "number_of_payments": 15,
    "last_paid_amount": 15.99,
    "last_payment_date": 1603885746,
    "last_invoice_url": "https://example.com/invoice.html",
    "last_payment_was_successful": true
  }
}

You can get details on every Customer Object field in the Customer model article.

🛑 Error Responses

You may get one of the following error status codes and responses. More info on the errors is available here.

400 Bad Request

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "customer",
      "message": "This value should be of type numeric."
    },
    {
      "code": "filter[0].field",
      "message": "This value should not be blank."
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}

If you have any questions regarding the REST API, feel free to chat us any time.

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?