Get all customers

Fetch a list of all customers or a bunch of customers
Written by Konstantine
Updated 1 year ago

You can get all of your customers or a bunch of customers with this method. If you want to get just one customer by her id, use Get a single customer method instead. To find customers by the value of their attributes, use Search for customers method.

➡️ Request

URL https://api.helpcrunch.com/v1/customers?sort=customers.firstSeen
Method GET
Headers Authorization: Bearer <your_api_key>

Read more about authorization header here.


Sorting options

To sort customers in descending order, use order=desc parameter in the query string. For ascending order use order=asc

Sorting option Description
customers.firstSeen by date of the customers' first visit
customers.lastSeen by date of the customers' last visit


✅ 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.

How to get all customers

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 query string of the GET request.

Default limit is 100 and it can not be bigger than that. Default offset is 0

To page through all the available customers, first, send a request without any parameters and extract the total number of customers from the JSON response you'll get.

Then send subsequent requests with increasing offsets and a fixed limit until you get all the data.

https://api.helpcrunch.com/customers?offset=100&limit=100
https://api.helpcrunch.com/customers?offset=200&limit=100
https://api.helpcrunch.com/customers?offset=300&limit=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": "limit value is invalid"
        },
        {
            "code": "validation_error",
            "message": "sort value is invalid"
        },
        {
            "code": "validation_error",
            "message": "order 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?