Hiver API

The Hiver APIs allows you to programmatically access your Hiver Data. You can use Hiver REST APIs to build custom integrations for your team.

If you need any help, you can refer to our help article here.

Overview

To get started you can get the API keys created by referring to the Getting API Key section below. You need these API keys to access any of the APIs listed below.

Getting Started

Getting API key

You need to create an API key to access the Hiver APIs. Please follow these steps to get an API key

    Select...
    curl 'https://api2.hiverhq.com/v1/inboxes' --header 'Authorization: Bearer <your-access-token>'

    If you suspect that any of your API keys have been compromised, you must take immediate action and delete them from the Hiver admin panel.

    Authentication

    You need to have access to a Hiver API key to access any of these Hiver APIs. Do note that the API key can be created by an administrator in Hiver. The API key will have the access privileges of an admin user. It is very important to store and use your API keys safely.

    Request Format

    Hiver uses HTTP methods like GETPOSTPATCH etc for different types of operations. Depending on the type of the request, the query parameters, request body, URL path needs to be formed.

    For more details, refer to individual APIs in the API reference section below.

    Response format

    JSON

    json
    Select...
    {
    "data":{
    ...
    }
    }

    JSON

    json
    Select...
    {
    "results": [
    {..},
    ],
    "pagination": {
    "next_page": "<next-page-token>"
    }
    }

    For the paginated results, use the next page token in the subsequent request to get further results. Keep continuing to get the next page until the next_page returns null

    Pagination

    Some endpoints return a list like list of inboxes etc. These endpoints return paginated results. To get the complete list, you need to implement the fetching of paginated lists.

    These endpoints support following parameters

    Query Parameter

    Description

    limit

    Limits the number of results in a page. Supported values are 10-100. Defaults to 10

    sort_by

    The field based on which the result need to be sorted. Refer to individual APIs to find the supported fields

    sort_order

    Ascending, Descending order. Supported values: ascdesc. Defaults to asc

    next_page

    If sent the next page corresponding to the page token is sent

    All of these field are optional, depending on the endpoint being used.

    Errors

    The error response will have an appropriate HTTP status code attached in the response. In addition to this, there could also be message, in some cases, to help identify the errors

    Status Code

    Description

    200

    Success

    204

    Success - No response

    400

    Bad request - Request sent without required params

    401, 403

    Forbidden - Not authorised to access

    404

    Not found - Request entity not found

    429

    Too many requests

    500

    Internal server error - If this happens, get in touch with us, or watch for any degradation in status.hiverhq.com

    JSON

    json
    Select...
    {
    "errors": [
    {"message": "Actual Error message"}
    ..
    ]
    }
    or
    {
    "Message": "Actual Error Message"
    }

    Refer to the rate-limiting section to get to know more about rate-limiting enforced by Hiver.

    Rate limits

    Hiver enforces rate-limits based per account. The current rate is limited at 1 RPS (request per second). Once you hit the limit, you’ll start getting 429 Too Many Requests error in the response. If you get this error, retry with an exponential backoff. Continuous retries with 429 error could result in the client-ip/api-key getting blacklisted. Also, the APIs are limited to 5000 requests per day. Please get in touch with us if you want to increase this.

    Base URL

    Production:

    https://api2.hiverhq.com/v1

    Language Box

    Was this section helpful?

    What made this section unhelpful for you?

    Inbox

    An Inbox is an entity that has conversations & users. Most common form of an Inbox is a shared mailbox (https://hiverhq.com/shared-inbox) which manages emails. The APIs only manage the shared mailbox. We plan to add other type of inboxes in the APIs soon. It can have tags to help manage the conversations better.

    JSON

    json
    Select...
    {
    "id": "101",
    "display_name": "Customer Support",
    "channel_type": "email",
    "email": "info@hiver.com",
    "inbox_type": "user",
    "is_authorised": false,
    "source_user": {
    "id": "765676",
    "email": "info@hiver.com"
    },
    "created_at": 176878888,
    "updated_at": 176878888
    }

    JSON

    json
    Select...
    {
    "id": "456",
    "first_name": "Phoebe",
    "last_name": "Buffay",
    "email": "p.buffay@friends.com",
    "phone_number": "+19876543444",
    "is_joined": false
    }

    JSON

    json
    Select...
    {
    "id": "56789",
    "name": "Priority",
    "color_code": "#ce93d8",
    "type": "user",
    "created_at": 1708945347
    }

    Conversations

    A conversation can be part of one or more inboxes. It can be assigned to a member of the inbox, have a status and tags associated with it.

    JSON

    json
    Select...
    {
    "id": "234232",
    "assignee": {
    "assignee_type": "user",
    "assignee_id": "1028399"
    },
    "status": "open",
    "tag_ids": [
    "1234322", "343434"
    ]
    }