Hiver

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

## 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

- Go to Developer settings in the left panel in the Hiver admin panel. 
- Click on Create app.
- Enter a name for the app and click on Create to Generate the API keys.
- You'll see the app created with the API key. Click on the copy icon to get the API key copied. These API keys can be used as a bearer token as follows
```curl
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 `GET`, `POST`, `PATCH` 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

The response will be a JSON object. The usual object be in the format as follows, enclosed in a data object

```json
{
  "data":{
    ...
  }
}
```

The response for list will be as follows:
```json
{
  "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: `asc`, `desc`. 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 |


The error messages will be in one of the following formats:
 
```json
{
  "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 retrie with 429 error could result in the client-ip/api-key getting blacklisted.

Hiver API

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.

Following is an example of an Inbox object
```json
    {
      "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
    }
```

Following is an example of an Inbox User object
```json
    {
      "id": "456",
      "first_name": "Phoebe",
      "last_name": "Buffay",
      "email": "p.buffay@friends.com",
      "phone_number": "+19876543444",
      "is_joined": false
    }
```

Following is an example of an Inbox Tag object
```json
    {
      "id": "56789",
      "name": "Priority",
      "color_code": "#ce93d8",
      "type": "user",
      "created_at": 1708945347
    }
```


Inbox

List all the inboxes

Get an inbox by id

Get all users in the inbox

Search users in the inbox

Get tags in the inbox

Conversations

Get conversations in the inbox

Get a conversation in the inbox

Update conversation in the inbox

Hiver OpenAPI Prod

Production

<p class="slate-p " >The Hiver APIs allows you to programmatically access your Hiver Data. You can use Hiver REST APIs to build custom integrations for your team.</p><p class="slate-p slate-indent-0" style="0px">If you need any help, you can refer to our help article <a href="https://help.hiverhq.com/hiver-api/hiver-api" target="_blank">here</a>.</p><p class="slate-p slate-indent-0" style="0px"></p><h2 class="slate-h2 " >Overview</h2><p class="slate-p slate-indent-0" style="0px">To get started you can get the API keys created by referring to the <code class="slate-code">Getting API Key</code> section below. You need these API keys to access any of the APIs listed below.</p><p class="slate-p " ></p><h3 class="slate-h3 " >Getting Started</h3><p class="slate-p " ></p><h4 class="slate-h4 " >Getting API key</h4><p class="slate-p " >You need to create an API key to access the Hiver APIs. Please follow these steps to get an API key</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Go to Developer settings in the left panel in the Hiver admin panel.</div></li><li class="slate-li " ><div style="position:relative">Click on Create app.</div></li><li class="slate-li " ><div style="position:relative">Enter a name for the app and click on Create to Generate the API keys.</div></li><li class="slate-li " ><div style="position:relative">You’ll see the app created with the API key. Click on the copy icon to get the API key copied. These API keys can be used as a bearer token as follows</div></li></ul><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">curl 'https://api2.hiverhq.com/v1/inboxes'  --header 'Authorization: Bearer <your-access-token>' </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><p class="slate-p " >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.</p><p class="slate-p " ></p><h4 class="slate-h4 " >Authentication</h4><p class="slate-p " >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.</p><p class="slate-p " ></p><h4 class="slate-h4 " >Request Format</h4><p class="slate-p " >Hiver uses HTTP methods like <span style="background-color:rgb(249, 242, 244);color:rgb(199, 37, 78)"><code class="slate-code">GET</code></span>, <span style="background-color:rgb(249, 242, 244);color:rgb(199, 37, 78)"><code class="slate-code">POST</code></span>, <span style="background-color:rgb(249, 242, 244);color:rgb(199, 37, 78)"><code class="slate-code">PATCH</code></span> etc for different types of operations. Depending on the type of the request, the query parameters, request body, URL path needs to be formed.</p><p class="slate-p " >For more details, refer to individual APIs in the API reference section below.</p><p class="slate-p " ></p><h4 class="slate-h4 " >Response format</h4><p class="slate-p " >The response will be a JSON object. The usual object be in the format as follows, enclosed in a data object</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;data&quot;:{</div><div class="slate-code_line">    ...</div><div class="slate-code_line">  }</div><div class="slate-code_line">}</div><div class="slate-code_line"></div></code></pre></div><p class="slate-p " >The response for list will be as follows:</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;data&quot;: {</div><div class="slate-code_line">    &quot;results&quot;: [</div><div class="slate-code_line">      {..},</div><div class="slate-code_line">    ],</div><div class="slate-code_line">    &quot;pagination&quot;: {</div><div class="slate-code_line">      &quot;next_page&quot;: &quot;&lt;next-page-token&gt;&quot;</div><div class="slate-code_line">    }</div><div class="slate-code_line">  }</div><div class="slate-code_line">}</div><div class="slate-code_line"></div></code></pre></div><p class="slate-p slate-indent-0" style="0px">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 <code class="slate-code">null</code></p><p class="slate-p " ></p><h3 class="slate-h3 " >Pagination</h3><p class="slate-p " >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.</p><p class="slate-p " >These endpoints support following parameters</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:100px;">Title</div><div style="width:100px;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Query Parameter</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Description</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >limit</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Limits the number of results in a page. Supported values are 10-100. Defaults to 10</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >sort_by</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The field based on which the result need to be sorted. Refer to individual APIs to find the supported fields</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >sort_order</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-0" style="0px">Ascending, Descending order. Supported values: asc, <code class="slate-code">desc</code>. Defaults to <span style="background-color:rgb(249, 242, 244);color:rgb(199, 37, 78)">asc</span></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >next_page</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >If sent the next page corresponding to the page token is sent</p></td></div></tr></tbody></table></div></div><p class="slate-p " >All of these field are optional, depending on the endpoint being used.</p><h3 class="slate-h3 " >Errors</h3><p class="slate-p " >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</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:100px;">Title</div><div style="width:100px;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Status Code</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Description</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >200</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Success</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >204</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Success - No response</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >400</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Bad request - Request sent without required params</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >401, 403</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Forbidden - Not authorised to access</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >404</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Not found - Request entity not found</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >429</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Too many requests</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >500</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Internal server error - If this happens, get in touch with us, or watch for any degradation in <a href="http://status.hiverhq.com/" target="_blank">status.hiverhq.com</a></p></td></div></tr></tbody></table></div></div><p class="slate-p " >The error messages will be in one of the following formats:</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;errors&quot;: [</div><div class="slate-code_line">    {&quot;message&quot;: &quot;Actual Error message&quot;}</div><div class="slate-code_line">    ..</div><div class="slate-code_line">  ]</div><div class="slate-code_line">}</div><div class="slate-code_line">or</div><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;Message&quot;: &quot;Actual Error Message&quot;</div><div class="slate-code_line">}</div><div class="slate-code_line"></div></code></pre></div><p class="slate-p " >Refer to the rate-limiting section to get to know more about rate-limiting enforced by Hiver.</p><p class="slate-p " ></p><h3 class="slate-h3 " >Rate limits</h3><p class="slate-p slate-indent-0" style="0px">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 <code class="slate-code">429 Too Many Requests</code> 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.</p><p class="slate-p " ></p>

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 

To get started you can get the API keys created by referring to the 

 section below. You need these API keys to access any of the APIs listed below.

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

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.

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.

 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.

The response will be a JSON object. The usual object be in the format as follows, enclosed in a data object

The response for list will be as follows:

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 

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

Title

Description

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

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

The error messages will be in one of the following formats:

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

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 

 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.

<p class="slate-p " >An Inbox is an entity that has conversations &amp; users.
Most common form of an Inbox is a shared mailbox (<a href="https://hiverhq.com/shared-inbox" target="_self">https://hiverhq.com/shared-inbox</a>) 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.</p><p class="slate-p " >Following is an example of an Inbox object</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">    {</div><div class="slate-code_line">      &quot;id&quot;: &quot;101&quot;,</div><div class="slate-code_line">      &quot;display_name&quot;: &quot;Customer Support&quot;,</div><div class="slate-code_line">      &quot;channel_type&quot;: &quot;email&quot;,</div><div class="slate-code_line">      &quot;email&quot;: &quot;info@hiver.com&quot;,</div><div class="slate-code_line">      &quot;inbox_type&quot;: &quot;user&quot;,</div><div class="slate-code_line">      &quot;is_authorised&quot;: false,</div><div class="slate-code_line">      &quot;source_user&quot;: {</div><div class="slate-code_line">        &quot;id&quot;: &quot;765676&quot;,</div><div class="slate-code_line">        &quot;email&quot;: &quot;info@hiver.com&quot;</div><div class="slate-code_line">      },</div><div class="slate-code_line">      &quot;created_at&quot;: 176878888,</div><div class="slate-code_line">      &quot;updated_at&quot;: 176878888</div><div class="slate-code_line">    }</div></code></pre></div><p class="slate-p " >Following is an example of an Inbox User object</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">    {</div><div class="slate-code_line">      &quot;id&quot;: &quot;456&quot;,</div><div class="slate-code_line">      &quot;first_name&quot;: &quot;Phoebe&quot;,</div><div class="slate-code_line">      &quot;last_name&quot;: &quot;Buffay&quot;,</div><div class="slate-code_line">      &quot;email&quot;: &quot;p.buffay@friends.com&quot;,</div><div class="slate-code_line">      &quot;phone_number&quot;: &quot;+19876543444&quot;,</div><div class="slate-code_line">      &quot;is_joined&quot;: false</div><div class="slate-code_line">    }</div></code></pre></div><p class="slate-p " >Following is an example of an Inbox Tag object</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">    {</div><div class="slate-code_line">      &quot;id&quot;: &quot;56789&quot;,</div><div class="slate-code_line">      &quot;name&quot;: &quot;Priority&quot;,</div><div class="slate-code_line">      &quot;color_code&quot;: &quot;#ce93d8&quot;,</div><div class="slate-code_line">      &quot;type&quot;: &quot;user&quot;,</div><div class="slate-code_line">      &quot;created_at&quot;: 1708945347</div><div class="slate-code_line">    }</div></code></pre></div><p class="slate-p " ></p>

An Inbox is an entity that has conversations & users.
Most common form of an Inbox is a shared mailbox (

) 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.

Following is an example of an Inbox object

Following is an example of an Inbox User object

Following is an example of an Inbox Tag object

Priority

<p class="slate-p " >List all the inboxes</p><p class="slate-p " ></p>

Authorization

data

<p class="slate-p" placeholder="Type / for widgets">Get an Inbox by Id</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

inbox_id

<p class="slate-p " >Get all users in the inbox</p><p class="slate-p " ></p>

<p class="slate-p " >Search users in the inbox</p><p class="slate-p " ></p>

Email address to be searched for by exact match

email

<p class="slate-p " >Get tags in the inbox</p><p class="slate-p " ></p>

<p class="slate-p " >Search tags in the inbox</p><p class="slate-p " ></p>

name

<p class="slate-p " >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.</p><p class="slate-p " >Following is an example of a Conversation object</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">    {</div><div class="slate-code_line">      &quot;id&quot;: &quot;234232&quot;,</div><div class="slate-code_line">      &quot;assignee&quot;: {</div><div class="slate-code_line">        &quot;assignee_type&quot;: &quot;user&quot;,</div><div class="slate-code_line">        &quot;assignee_id&quot;: &quot;1028399&quot;</div><div class="slate-code_line">      },</div><div class="slate-code_line">      &quot;status&quot;: &quot;open&quot;,</div><div class="slate-code_line">      &quot;tag_ids&quot;: [</div><div class="slate-code_line">        &quot;1234322&quot;, &quot;343434&quot;</div><div class="slate-code_line">      ]</div><div class="slate-code_line">    }</div></code></pre></div><p class="slate-p " ></p>

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.

Following is an example of a Conversation object

Sections