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

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

✅ Successful Response

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

{
  "data": [
    {
      "id": 542335,
      "name": "John Doe",
      "email": "[email protected]",
      "userId": "user_1234567890",
      "company": "Example Inc.",
      "phone": "+10233456781",
      "firstSeen": "1603885746",
      "lastSeen": "1603885746",
      "location": {
        "regionCode": "Kyyivs'ka Oblast",
        "countryCode": "UA",
        "city": "Kyiv"
      },
      "device": {
        "id": 542335,
        "ip": "192.168.1.1",
        "timezone": "Europe/Kiev",
        "platform": "desktop",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36"
      },
      "unsubscribed": false,
      "blocked": false,
      "source": "https://example.com",
      "referer": "https://example.com",
      "lastPage": "https://example.com",
      "locale": "uk",
      "createdFrom": "telegram",
      "integrationId": "465847687",
      "notes": "Lorem ipsum",
      "tags": [
        {
          "name": "vip",
          "color": "#ff0000"
        }
      ],
      "customData": {
        "subscription_status": "active",
        "number_of_payments": 15,
        "last_paid_amount": 15.99,
        "last_payment_date": 1603885746,
        "last_invoice_url": "https://example.com/invoice.html",
        "last_payment_was_successful": true
      }
    }
  ],
  "total": 256
}

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": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "customer",
      "message": "This value should be of type numeric."
    },
    {
      "code": "filter[0].field",
      "message": "This value should not be blank."
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}

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

👩‍💻 Happy Coding! 👨‍💻