Hello 👋🏼 How can we help?

Get started with REST API

The API basics to help you get started
Written by Konstantine
Updated 5 months ago

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.

Please don't use Legacy API Key as it is compatible only with the legacy REST API that will be discontinued soon.

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.

Make sure you pass the entire key without any spaces or extra symbols.


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.

The default overall requests limit is 120 per minute


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_chat_value",
            "message": "comparison"
        },
        {
            "code": "invalid_chat_value",
            "message": "Invalid chat ID"
        },
        {
            "code": "invalid_chat_value",
            "message": "customer value is invalid"
        },
        {
            "code": "invalid_chat_value",
            "message": "assignee value is invalid"
        },
        {
            "code": "invalid_value",
            "message": "status is not a valid integer"
        },
       {
            "code": "invalid_field",
            "message": "Field chats.customer.tagsDataff is invalid"
        },
        {
            "code": "invalid_operator",
            "message": "Operator ~~~~ is invalid"
        }
    ]
}


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": "invalid_token",
            "message": "Invalid token"
        }
    ]
}


404 Not Found

We were unable to find anything matching your request.

{
    "errors": [
        {
            "code": "chat_not_found",
            "message": "Chat is missing"
        }
    ]
}


429 Too Many Requests

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

{
    "errors": [
        {
            "code": "too_many_requests",
            "message": "You have exceeded your requests limit"
        }
    ]
}


5️⃣ Endpoints

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

Endpoint What you can do
Customers Add new customers or get/update data of the existing ones.
Chats Get/update your chats data. Create new chats on behalf of your customers.
Messages Post messages to specific chats on behalf of your customers.
Agents Get your team members information and unsubscribe them from HelpCrunch email newsletters programmatically.
Departments Get info about your departments
Applications Get info about your website widgets and iOS/Android apps
Organization Get basic info about your organization account and team availability status

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

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?