Welcome to HelpCrunch REST API 👋

REST API allows you to access and manipulate your HelpCrunch data. Request methods are used in accordance with HTTP:

• GET is used to read one or more entities;
• POST is used to create or update entities;
• PUT is used to update entities;
• DELETE is used to delete entities;
• JSON format is used for requests, responses and error messages;
• Responses use standard HTTP codes.

If you want to subscribe to real-time updates on your chats or customers, check out our Webhooks docs.

Before you start using the API, read through the following five basics 👇

1️⃣ API endpoint

HelpCrunch REST API is the HTTPS-only API that runs at:

https://api.helpcrunch.com/v1

2️⃣ Authentication

You should authenticate all your HTTP requests to HelpCrunch API with a help of your API key.

To get the API key, go to Settings → Developers → Public API and copy your API Key from there.

In order to authenticate your HTTP requests, you should add an Authorization header to your requests and specify your API key there.

Authorization: Bearer <your_api_key_goes_here>

You don't need to do any extra manipulations with your API key. It is permanent and never expires.

3️⃣ Rate limiting

In order to protect HelpCrunch from API traffic spikes that could put our database at risk we utilize a rate-limiting. When you get rate-limited, you will start receiving 429 Too Many Requests HTTP errors in response to your requests.

4️⃣ Errors

For your convenience, we added 🛑 Error Responses section to each article describing a specific API method with the exact response codes and examples. 

Depending on the exact method, you can get one of the following error status codes and responses:

400 Bad Request

The request could not be understood by HelpCrunch server due to malformed syntax or invalid attribute value. DO NOT repeat such requests without modifications.

{
  "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

This means that something is wrong with your API key or it's not added to the request headers at all. Make sure you pass it as described in the Authentication section above.

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

404 Not Found

We were unable to find anything matching your request.

{
  "errors": [
    {
      "code": "not_found",
      "message": "Chat not found"
    }
  ]
}

429 Too Many Requests

You reached a rate-limit of 120 API calls per minute.

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

5️⃣ Endpoints

Here's the list of all available endpoints you can use to access and control your HelpCrunch data.

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

👩‍💻 Happy Coding! 👨‍💻