> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveinspect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Efficient Integration With the Hive Inspect API

> Keep your Hive Inspect API integration fast and well inside your monthly quota: use webhooks instead of polling, use what list responses already include, fetch records in batches and sync only what changed.

> [!NOTE]
>
> **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon. To ask for early access, message us from the chat bubble in your dashboard.

Every successful request counts toward your company's [monthly quota](https://docs.hiveinspect.com/api/rate-limits-and-errors.md#monthly-quota). A well-built integration needs only a few requests a day, even for a busy company, because Hive tells it about changes and every response carries everything it needs.

## 1. Let Hive tell you about changes

Checking the API on a timer to see whether something changed uses requests even when nothing did. [Webhooks](https://docs.hiveinspect.com/api/webhooks.md) send you a message the moment something changes, and **webhook messages do not count toward your quota**.

| To know when… | Subscribe to |
| - | - |
| A booking is confirmed, moved or canceled | `inspection.confirmed`, `inspection.rescheduled`, `inspection.canceled` |
| A report is published | `inspection.published` |
| An inspection is paid in full | `inspection.paid` |
| Every agreement is signed | `inspection.agreements_signed` |
| An inspection is paid, signed, published and over, for example to ask for a review | `inspection.completed` |
| A contact is added, edited, tagged or deleted | `contact.created`, `contact.updated`, `contact.deleted` |

Each message carries the full record: the inspection with its clients and agents (names, emails, phones), price and payment status, and its reports and agreements where relevant. You usually do not need a request afterwards. See [Events and payloads](https://docs.hiveinspect.com/api/webhook-events.md).

## 2. Use what list responses already include

A list returns the same fields as the single-record endpoint. Each inspection in `GET /v1/inspections` already includes its contacts (id, role, name, email, phone and agency), inspectors, services, price and payment, agreements and reports.

> [!TIP]
>
> Do not list records and then fetch each one again with `GET /v1/inspections/{id}` or `GET /v1/contacts/{id}`. The list already has the same data.

## 3. Fetch many records in one request

* **Use the largest page.** Send `limit=200`. The default is 50, and a smaller page means more requests for the same data.
* **Fetch by id in batches.** Contacts, agencies and inspections accept `ids` with up to 200 ids separated by commas. One request replaces up to 200 single-record requests. See [Fetch several records by id](https://docs.hiveinspect.com/api/pagination.md#fetch-several-records-by-id).

## 4. Sync only what changed

Store the time of your last sync and send it as `updated_since`. Only records created or changed since then come back, so an ordinary day is one or two pages. See [Sync only what changed](https://docs.hiveinspect.com/api/pagination.md#sync-only-what-changed).

## 5. Keep a local copy for lookups

If your system matches records by email or name, download your contacts once (`GET /v1/contacts?limit=200`, following `next_cursor`) and keep the copy current with the contact webhooks. Then look up emails in your own copy. Looking up one email per request, again and again, uses your quota quickly.

## 6. When you must poll, poll less

Some systems cannot receive webhooks. If yours cannot:

* Ask one filtered question instead of many. For example, inspections ready for a review: `GET /v1/inspections?status=confirmed&paid=true&agreements_signed=true&published=true&scheduled_after=…&limit=200`.
* Add `updated_since` so each check returns only changes.
* Check every 15 to 60 minutes, not every minute. Most data in an inspection business changes a few times a day.

## 7. Watch your usage

Every response to a request with a valid key includes `Hive-Quota-Used`, `Hive-Quota-Remaining` and `Hive-Quota-Next-Reset-Date`. Your company's usage this month is also on **Business Tools → API Access**. If the numbers climb faster than you expect, look for a loop that requests the same records again and again.

## Example: keep a CRM in sync and send review requests

### 1. Once: load what you have

Download your contacts and recent inspections with `limit=200`. For about 3,000 contacts that is 15 requests.

### 2. Once: subscribe

Add a webhook endpoint for `contact.created`, `contact.updated`, `contact.deleted` and `inspection.completed`.

### 3. Every day: react to messages

Update your copy from each contact message. When `inspection.completed` arrives, send the review request to the clients and agents in the message. No request to the API is needed.

### 4. Once a day: catch anything missed

Run `GET /v1/contacts?updated_since=…&limit=200` and `GET /v1/inspections?updated_since=…&limit=200` with yesterday's time. That is usually 2 requests.

This setup typically uses a few requests a day, far inside the monthly quota.

## Quick reference

| Instead of | Do this |
| - | - |
| Checking for changes every few minutes | Subscribe to [webhooks](https://docs.hiveinspect.com/api/webhooks.md) |
| Listing records, then fetching each one | Use the list response, it has the same fields |
| Fetching records one id at a time | Send up to 200 `ids` in one request |
| Small pages (`limit=5`, `limit=25`) | `limit=200` |
| Downloading everything on every sync | `updated_since` with your last sync time |
| One request per email lookup | A local copy kept current by contact webhooks |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.