Hello 👋🏼 How can we help?

Create customer

Add a single customer to your account
Written by Konstantine
Updated 2 weeks 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 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": "Hakim Zarakim",
    "email": "hzarakim@example.com",
    "userId": "example_22",
    "company": "example",
    "source": "https://google.com",
    "locale": "en",
    "firstSeen": 1593547200,
    "notes": "Hakim Zarakim could be a soccer player, but preferred to develop his magic skills instead.",
    "customData": [
        {
            "property": "Subscription status",
            "value": "Active"
        }
    ],
    "tags": [
        {
            "name": "Lead",
            "color": "#ccc"
        },
        {
            "name": "Paid"
        }
    ]
}


Tips

  • All dates should be passed in the 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.
❗ Important note about customData 
We do not validate your customData attributes currently. The only error you may get is when you pass the customData not as an Array. Therefore, you should always check the type of data you're sending and make sure it matches the data type of the attribute.


✅ Successful Response

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

{
    "id": 7831827,
    "name": "Hakim Zarakim",
    "email": "hzarakim@example.com",
    "userId": "example_22",
    "company": "example",
    "phone": null,
    "firstSeen": 1593547200,
    "lastSeen": 1593547200,
    "location": {
        "regionCode": null,
        "countryCode": null,
        "city": null
    },
    "device": null,
    "unsubscribed": false,
    "blocked": false,
    "source": "https://google.com",
    "referer": null,
    "locale": "en",
    "notes": "Hakim Zarakim could be a soccer player, but preferred to develop his magic skills instead.",
    "lastPage": null,
    "tags": [
        {
            "name": "Lead",
            "color": "#cсс"
        },
        {
            "name": "Paid",
            "color": "#c377e0"
        }
    ],
    "customData": [
        {
            "property": "Subscription status",
            "value": "Active"
        }
    ]
}

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": "validation_error",
            "message": "email value is invalid"
        },
        {
            "code": "validation_error",
            "message": "userId value is invalid"
        },
        {
            "code": "validation_error",
            "message": "source value is invalid"
        }
    ]
}

401 Unauthorized

{
    "errors": [
        {
            "code": "invalid_token",
            "message": "Invalid token"
        }
    ]
}

429 Too Many Requests

{
    "errors": [
        {
            "code": "too_many_requests",
            "message": "You have exceeded your requests limit"
        }
    ]
}

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

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?