REST API Reference

How to use

HelpCrunch provides you with a public API that can be used to add and update data of your customers without having them load a HelpCrunch widget.

To enable access to your organization API, you need to get your HelpCrunch organization API key first.

You can generate it in your HelpCrunch account at SettingsDevelopersGenerate Api Key and then copy it from the input below:

After that you need to add this key in Authorization header in your API requests like this:

Header: Authorization
Value: Bearer api-key="d0c538f41faf9c4d0c8fe7d020abca08ccb37a2f"

All your requests will be sent to your HelpCrunch organization domain to urls like this:

https://your-organization.helpcrunch.com/api/public/

All customer data must be sent in JSON format inside the request body.
Check the add customer method overview below to see the full request example.
Also, check the full customer fields list.

Add new customer

For example, you want to add your new customer, Ivan Dobsky to your HelpCrunch account.
The API request for it will look like this:
Url: https://your-organization.helpcrunch.com/api/public/customers
Method: PATCH
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″
Body (JSON):


[
  {
    "user_id": "19638",
    "name": "Ivan Dobsky",
    "company": "Microsoft",
    "email": "test-user@example.com",
    "source": "https://some-source.com",
    "first_seen": "2011-11-12 12:12:12",
    "unsubscribed": false,
    "notes": "Any text notes about your user",
    "status": 1,
    "custom_data": {
      "current_subscription": "suspended",
      "money_spent": 4000,
      "registration_data": "2017-10-05",
      "used_paycode": true
    },
    "tags": [
      { "name": "Lead" },
      {
        "name": "Bug",
        "color": "#FF0000"
      }
    ]
  }
]

Responses:

  • You will get “204 No Content” if everything is okay (and you can check that user data is imported at your contacts page)
  • You will get “401 Unauthorized” if api-key in Authorization header is wrong or absent
  • You will get “422 Unproccessable Entity” and “Request is not valid. Syntax error” if you use wrong customers data structure

Update customer

The request to update that user will look just the same as add customer request, provided you will use the same “user_id” field.

Important note:
Please, be aware, that if no user ID is specified a new user will always be generated.

Important note:
Also, please, keep in mind that “user_id” in HelpCrunch is a string, so don’t pass there things like “null”, “0”, “-1”, etc.

Update multiple customers

To update multiple users at once, you can use the same request as add/update customer and just add other users in request JSON body separated by commas:


[
  {
    "user_id": "123",
    "name": "Ivan Dobsky",
  },
  {
    "user_id": "124",
    "name": "Jane Doe",
  },
  {
    "user_id": "125",
    "name": "John Doe",
  }
]

Delete customer

You can delete one or multiple customers the same way you add/update customers. The only difference is that in this case you should use DELETE method. This will completely and permanently delete all customer data including the chat history.

You can pass id, user_id or email address (or all of them) in your request and this will delete all corresponding customers.

Important note:
If you have several customers in your database with the same email address – we’ll delete all of them.

Important note:
This operation is permanent and there is no way to restore the deleted data and the chat history.

Url: https://your-organization.helpcrunch.com/api/public/customers
Method: DELETE
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″
Body (JSON):


[
  {
    "user_id": "123",
  },
  {
    "email": "test@example.com",
  },
  {
    "id": 123123123,
  },
]

Responses:

  • You will get “200 Customers 1231341, 1231321 removed”, where 1231341 and 1231321 are customer ids, if everything is okay
  • You will get “404 Customer could not be found” if a customer does not exist or if you sent no data
  • You will get “401 Unauthorized” if api-key in Authorization header is wrong or absent
  • You will get “422 Unprocessable Entity” and “Request is not valid. Syntax error” if you use wrong customer data structure

Get full customer data

You can retrieve all customer personal data (including events, excluding your private notes and tags) by sending a GET request with customer id in your URL or by sending id, user_id or email in your get-parameters. This can come in handy for a full GDPR compliance.

Url: https://your-organization.helpcrunch.com/api/public/customers/1244343
Alternative: https://your-organization.helpcrunch.com/api/public/customers?email=test@example.com
Alternative: https://your-organization.helpcrunch.com/api/public/customers?id=1244343&user_id=8989899&email=test@example.com
Method: GET
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″
Responses:


{
    "id": 3360752,
    "name": "John Doe",
    "user_id": "123123",
    "email": "test@example.com",
    "referrer": "https://example.com/",
    "source": "https://example.com/somepage.html",
    "company": "Test",
    "phone": "+38093090909",
    "first_seen": "2018-05-24T08:05:28+0000",
    "locale": "en_US",
    "timezone": "Europe/Kiev",
    "last_seen": "2018-05-24T08:05:27+0000",
    "sessions": 9,
    "ip": "194.133.132.4/32",
    "country": "Ukraine",
    "country_code": "UA",
    "region": "Kyiv City",
    "city": "Kiev",
    "hostname": "yoursite.com",
    "last_page": "https://yoursite.com/somepage.html",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0"
}
  • You will get “401 Unauthorized” if api-key in Authorization header is wrong or absent
  • You will get “403 Access denied” if you are trying to get data from a customer that does not belong to your organization
  • You will get “404 Customers could not be found” if a customer does not exist or you sent no data
  • You will get “422 Unprocessable Entity” and “Request is not valid. Syntax error” if you use wrong customers data structure

Customer fields and format

This is the list of the customer fields you can send to HelpCrunch with add customer method.

User structure:

  • user_id: string – needed for user update / optional for new user – unique user ID, there are a lot of tricks here, please check the user authentication mode section to be sure you do everything right
  • email: string – optional – must be a valid email, not unique
  • name: string – optional – any string, not unique
  • company: string – optional – any string, not unique
  • phone: string – optional – any string, not unique, no checks for number
  • source: string – optional – url string, not unique, it’s the web page on your site what your customer opened first
  • referrer: string – optional – url string, not unique, it’s about the web page from which the user came to your application
  • first_seen: string – optional – date string, in “YYYY-MM-DD HH:MM:SS” format, it’s when your customer first appeared at your project
  • heard_from: string – optional – date string, in “YYYY-MM-DD HH:MM:SS” format, last time when your customer messaged you
  • blocked: string – optional – boolean, block email from that customer
  • unsubscribed: string – optional – boolean, do not send auto-messages to this customer
  • status: string – optional – number (1 – new, 2 – open, 3 – pending, 4 – hold, 5 – no communication, 6 – resolved, 7 – rejected)
  • custom_data: object – optional – an object with random key/value pairs, where value cannot be another object or array, be aware that all keys your pass there will appear as filters in your HelpCrunch account’s advanced search. Read more about it in the custom data section
  • tags: array – optional – array of objects with required string parameter “name” (case sensitive) and optional string parameter color (like “#FF0000”). Example { “name”: “Bug”, “color”: “#FF0000” }

Get your agents info

You can get data about your team from HelpCrunch REST API. For example you want to make a dashboard with active agents, so you can see if no agents are online and show a red light on your office monitor screen.
You’ll need to make API request like one below and check an “offline” field:
Url: https://your-organization.helpcrunch.com/api/public/agents
Method: GET
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″

Response:

[
{
"id": 1395,
"login": "agent@example.com",
"email": "agent@example.com",
"name": "Test Agent",
"role": "agent",
"disabled": false,
"mail_from": "agent@somedomain.helpcrunch.com",
"mail_from_name": "Test Agent",
"default_mail_subject": "You have a new message from Test Agent",
"reply_to": "agent@somedomain.helpcrunch.com",
"reply_to_name": "Test Agent",
"info_boxes": [],
"chat_rating_counters": {
"total": 2,
"great": 2,
"average": 0,
"poor": 0
},
"visible_in_chat": true,
"departments": [
29,
41
],
"online": false
}
]

Team / organization status

You can get data about your team being online / offline and basic data of your organization by this API request:
Url: https://your-organization.helpcrunch.com/api/public/organizations
Method: GET
Headers: Authorization: Bearer api-key=”842699d800d4df44831d8968ecfda46367717109″

Response:

{
"id": 135,
"name": "your-organization",
"domain": "your-organization",
"team_online": false,
"chat_enabled": true
}