Search for customers

Find customers by the value of their attributes
Written by Konstantine
Updated 1 year ago

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"
}
Tip: You can specify a number of tags in the customers.tagsData array. Search results will match all of them (e.g. tag1 AND tag2). If you want to make a search like tag1 OR tag2, you should add separate filters for each of the tags and use OR in the comparison attribute.


Accepted searchable fields

The value you search for has to match the type, otherwise the query will fail. For example, customers.createdAt accepts a date, so the value can't be a string such as "18 Jun 2020".
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

The operator should be put in as a string, for example ">"
The operator has to be compatible with the field's data type. You can't search with "<" for a string value as it works for integers and dates only.
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! 👨‍💻

Did this answer your question?