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

# Agencies in the API: Link Contacts to Their Brokerage

> Learn how contacts link to an agency in the Hive Inspect API, how to set the agency by id or by name, and how a contact can use its agency's address.

<p className="hive-locator">In the dashboard: <strong>Contacts → Manage Brokerages</strong></p>

<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.
</Note>

An agency is the brokerage an agent works for. The dashboard calls it a **brokerage**; the API calls it an **agency**. They are the same record. Each one has a name, an address, a phone number and a website, and any number of contacts can link to it.

## What a contact returns

| Field | What it holds |
| - | - |
| `agency_id` | The id of the linked agency, or `null` |
| `agency` | The linked agency's `id`, `name`, `phone` and `website`, or `null` |
| `agency_name` | The agency's name. Hive keeps it in sync when you rename the agency. |
| `uses_agency_address` | `true` when the contact's address is the agency's address |

A contact can have an `agency_name` with no `agency_id`. That is a name typed as plain text that does not match any of your agencies.

## Set a contact's agency

Agencies are read-only in the API. Create and edit them on the **Manage Brokerages** page in the dashboard, then link contacts to them.

<Steps titleSize="h3">
  <Step title="Find the agency">
    Search your agencies by name to get the id:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl "https://api.hiveinspect.com/v1/agencies?search=lone%20star" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Send the id on the contact">
    Send `agency_id` when you create or update a contact:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X PATCH "https://api.hiveinspect.com/v1/contacts/CONTACT_ID" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"agency_id": "AGENCY_ID"}'
    ```
  </Step>
</Steps>

To remove the link, send `"agency_id": null`.

### Link by name instead

You can send `agency_name` without an id:

* If the name matches one of your agencies, Hive links the contact to it. Upper and lower case and extra spaces do not matter.
* If it matches nothing, Hive keeps the name as plain text and the contact stays unlinked. The API never creates an agency from a name.

When you send both, `agency_id` wins. Prefer `agency_id`, because a name can be misspelled.

## Use the agency's address

A contact can follow its agency's address instead of keeping its own.

* **A contact with no address starts following the agency** the first time you link it. The response then shows the agency's address on the contact, with `uses_agency_address` set to `true`.
* **Sending an address stops it.** If you update any address field on a contact that follows its agency, Hive keeps your address and sets `uses_agency_address` to `false`.
* **You can choose.** Send `"uses_agency_address": true` to follow the agency, or `false` to keep the contact's own address.

When the agency's address changes in the dashboard, every contact that follows it updates too.

## Find contacts by agency

List everyone at an agency with the `agency_id` filter:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/contacts?agency_id=AGENCY_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Contact stats accept the same filter, and each stats row includes `agency_id`, so you can total inspections and revenue by agency.


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