Hello 👋🏼 How can we help?

Add a new customer via REST API

Use the following API request if you want to add a new customer to HelpCrunch.
Written by Konstantine
Updated 1 year ago

Let's say you want to add your new customer Ivan Dobsky to your HelpCrunch account.

The API request for it will look like this:

Url: https://your-organization.helpcrunch.com/api/public/customers
Method: PATCH
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″
Body (JSON):

    "user_id": "19638",
    "name": "Ivan Dobsky",
    "company": "Microsoft",
    "email": "test-user@example.com",
    "source": "https://some-source.com",
    "first_seen": "2011-11-12 12:12:12",
    "unsubscribed": false,
    "notes": "Any text notes about your user",
    "status": 1,
    "custom_data": {
      "current_subscription": "suspended",
      "money_spent": 4000,
      "registration_data": "2017-10-05",
      "used_paycode": true
    "tags": [
      { "name": "Lead" },
        "name": "Bug",
        "color": "#FF0000"


  • You will get “204 No Content” if everything is okay (and you can check that user data is imported at your contacts page)
  • You will get “401 Unauthorized” if api-key in Authorization header is wrong or absent
  • You will get “422 Unproccessable Entity” and “Request is not valid. Syntax error” if you use wrong customers data structure

Customer fields and format for the HelpCrunch REST API

This is the list of the customer fields you can send to HelpCrunch with the add customer method.

User structure:

user_id: string – needed for user update / optional for new user – unique user ID, there are a lot of tricks here, please check the user authentication mode section to be sure you do everything right

email: string – optional – must be a valid email, not unique

name: string – optional – any string, not unique

company: string – optional – any string, not unique

phone: string – optional – any string, not unique, no checks for number

source: string – optional – url string, not unique, it’s the web page on your site what your customer opened first

referrer: string – optional – url string, not unique, it’s about the web page from which the user came to your application

first_seen: string – optional – date string, in “YYYY-MM-DD HH:MM:SS” format, it’s when your customer first appeared at your project

heard_from: string – optional – date string, in “YYYY-MM-DD HH:MM:SS” format, last time when your customer messaged you

blocked: string – optional – boolean, block email from that customer

unsubscribed: string – optional – boolean, do not send auto-messages to this customer

status: string – optional – number (1 – new, 2 – open, 3 – pending, 4 – hold, 5 – no communication, 6 – resolved, 7 – rejected)

custom_data: object – optional – an object with random key/value pairs, where value cannot be another object or array, be aware that all keys your pass there will appear as filters in your HelpCrunch account’s advanced search. Read more about it in the custom data section

tags: array – optional – array of objects with required string parameter “name” (case sensitive) and optional string parameter color (like “#FF0000”). Example { “name”: “Bug”, “color”: “#FF0000” }

Did this answer your question?