You can search for multiple customers by the value of their attributes in order to fetch exactly the ones you want.
➡️ Request
URL | https://api.helpcrunch.com/v1/customers/search |
Method | POST |
Headers | Authorization: Bearer <your_api_key> |
Search filters should be placed to the body of your POST request. Check a couple of examples below.
Read more about authorization header here.
Example: Search with a single filter
{
"filter": [
{
"field": "customers.email",
"operator": "~",
"value": "gmail"
}
],
"limit": 5,
"offset": 0,
"sort": "customers.firstSeen",
"order": "DESC"
}
Example: Search with multiple filters
If you want to get customers that match all the filters, use "comparison": "AND"
attribute in the body of your POST request. To fetch customers matching any of the given filters, use OR
value instead.
{
"comparison": "OR",
"filter": [
{
"field": "customers.email",
"operator": "~",
"value": "gmail"
},
{
"field": "customers.tagsData",
"operator": "=",
"value": [{"name": "Paid"}]
}
],
"limit": 10,
"offset": 0,
"sort": "customers.lastSeen",
"order": "ASC"
}
Accepted searchable fields
Field | Type | Description |
customers.id | Integer | Unique id of the customer provided by HelpCrunch |
customers.name | String | Customer name |
customers.email | String | Customer email |
customers.company | String | Customer company |
customers.phone | String | Customer phone number |
customers.countryCode | String | Customer country code |
customers.city | String | Customer city |
customers.regionCode | String | Customer region code |
customers.tagsData | Array of Strings | Tags assigned to the chat, e.g. [{"name": "Lead"}, {"name": "Paid"}] |
customers.lastSeen | Date (UNIX timestamp) | Date and time of customer's last visit |
customers.userId | String | Unique id of the customer that you can pass to HelpCrunch with User Authentication |
Accepted operators
Operator | Valid Field Data Types | Description |
= | All data types | Equals |
!= | All data types (except arrays) | Doesn't Equal |
> | Integer or Date (UNIX Timestamp) | Greater than |
< | Integer or Date (UNIX Timestamp) | Lower than |
>= | Integer or Date (UNIX Timestamp) | Greater than or equal |
<= | Integer or Date (UNIX Timestamp) | Lower than or equal |
~ | String | Contains |
!~ | String | Doesn't Contain |
Sorting options
To specify the sorting type, you should add sort and order attributes to the body of your POST request.
"sort": "customers.firstSeen",
"order": "ASC"
You can sort customers by the following fields:
Field | Description |
customers.firstSeen | by date of the customers' first visit |
customers.lastSeen | by date of the customers' last visit |
To sort customers in descending order, use DESC value. For ascending order use ASC value.
✅ Successful Response
If your request has succeeded, you'll get a 200 OK success status code together with the following response body.
{
"total": 184,
"data": [
{
"id": 265555,
"name": "test",
"email": "test@test.com",
"userId": "test123abc_1",
"company": "test123abc",
"phone": null,
"firstSeen": null,
"lastSeen": 1588603952,
"location": {
"regionCode": "CA",
"countryCode": "US",
"city": "Los Angeles"
},
"device": {
"id": 28874635,
"ip": "192.168.1.1",
"timezone": "America/Los Angeles",
"platform": "desktop",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36"
},
"unsubscribed": false,
"blocked": false,
"source": "https://helpcrunch.com/",
"referer": "https://google.com/",
"locale": "en",
"notes": null,
"lastPage": "https://helpcrunch.com/zendesk-alternative.html",
"tags": [
{
"name": "direct",
"color": "#0079bf"
}
],
"customData": {
"Currency": "USD",
"Next payment date": "2020-09-01 00:40:00",
"Billing info added": true,
"Number of payments": 35,
"Subscription status": "active"
}
},
{
"id": 265580,
"name": "Lana Del Red",
"email": "lana.red@example.com",
"userId": null,
"company": null,
"phone": null,
"firstSeen": null,
"lastSeen": null,
"location": {
"regionCode": null,
"countryCode": null,
"city": null
},
"device": null,
"unsubscribed": false,
"blocked": false,
"source": null,
"referer": null,
"locale": null,
"notes": null,
"lastPage": null,
"tags": [
{
"name": "direct",
"color": "#0079bf"
}
],
"customData": {
"Tried Something": false
}
},
{
"id": 4994,
"name": "Serge Merge",
"email": "serge.merge@example.com",
"userId": "example_261",
"company": "example",
"phone": null,
"firstSeen": null,
"lastSeen": null,
"location": {
"regionCode": null,
"countryCode": null,
"city": null
},
"device": null,
"unsubscribed": false,
"blocked": false,
"source": null,
"referer": null,
"locale": null,
"notes": null,
"lastPage": null,
"tags": [
{
"name": "Lead",
"color": "#eb5a46"
},
{
"name": "Feature Request",
"color": "#0079bf"
},
{
"name": "Paid",
"color": "#61bd4f"
}
],
"customData": {
"Plan": "Premium",
"segment": null,
"Currency": "EUR",
"Became payer at": "2020-09-13 00:00:00",
"Next payment date": "2020-10-13 00:40:00",
"Billing info added": true,
"Number of payments": 1,
"Subscription status": "suspended"
}
},
{
"id": 7831682,
"name": "Vlad Darkula",
"email": "vlad.dark@transylmania.com",
"userId": "transylmania_6996",
"company": "transylmania",
"phone": null,
"firstSeen": 1593068924,
"lastSeen": 1593093642,
"location": {
"regionCode": "40",
"countryCode": "RO",
"city": "Cluj-Napoca"
},
"device": {
"id": 28889690,
"ip": "192.168.1.2",
"timezone": "Europe/Kiev",
"platform": "desktop",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36"
},
"unsubscribed": true,
"blocked": true,
"source": "https://www.blood.co.uk/",
"referer": null,
"locale": "ro",
"notes": null,
"lastPage": "https://www.blood.co.uk/who-can-give-blood/getting-an-appointment-to-give-blood/",
"tags": [],
"customData": {
"Plan": "Enterprise (Unlimited) $9999/mo",
"segment": "PotentialChurn_premium_seg1",
"Currency": "USD",
"Emails sent": 621,
"Next payment date": "2020-09-01 00:40:00",
"Billing info added": true,
"Number of payments": 35,
"Subscription status": "active"
}
}
]
}
You can get details on every Customer Object field in the Customer model article.
Limits
By default, this method returns only the first 100 customers. To get a different set of customers, you should use the offset and limit parameters in the body of your POST request.
"limit": 50,
"offset": 100,
The overall requests limit is 120 per minute
🛑 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": "order value is invalid"
},
{
"code": "validation_error",
"message": "sort value is invalid"
},
{
"code": "validation_error",
"message": "field value is invalid"
},
{
"code": "validation_error",
"message": "operator value is invalid"
},
{
"code": "invalid_field",
"message": "customers.id value is invalid"
},
{
"code": "validation_error",
"message": "limit value is invalid"
}
]
}
401 Unauthorized
{
"errors": [
{
"code": "invalid_token",
"message": "Invalid token"
}
]
}
404 Not Found
{
"errors": [
{
"code": "entity_not_found",
"message": "Customer not found"
}
]
}
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! 👨💻