# NetHunt

Connect NetHunt so the assistant finds contacts by phone and creates new ones in the folder you choose

> Full REST + WebSocket API reference: https://api.happ.tools/reference

NetHunt is a Gmail-based CRM, so it authenticates with the account email plus an API key. Once linked, the assistant finds contacts by phone number and creates new ones in the NetHunt folder you pick.

## Before you start [#before-you-start]

* **NetHunt account** on a paid plan — the API is exposed on all paid tiers.
* **Account email** and an **API key** (see below).
* **HAPP workspace** with at least one assistant configured to talk to customers.
* **Folders decided** — which NetHunt folder to search contacts in, and which one to create them in.

## Get your API key [#get-your-api-key]

1. From the NetHunt dashboard, click **Settings** at the bottom of the left sidebar.
2. In the **INTEGRATIONS** group pick **Apps and other integrations**.
3. Scroll to the bottom, click **GENERATE API KEY**, and copy the token.

<img alt="The API key at the bottom of Apps and other integrations in NetHunt" src="__img0" />

## Connect [#connect]

1. In HAPP open **Integrations** and find NetHunt under **Add a CRM**.
2. Click **Connect** — the modal asks for two fields.
3. Enter them and click **Connect**.

| Field   | Value                                   |
| ------- | --------------------------------------- |
| Email   | The email of your NetHunt account       |
| API Key | The token generated in NetHunt settings |

NetHunt moves to **My integrations** as a card showing its **Account Information** — workspace name and the date and time of connection.

## Settings [#settings]

Open the card's gear icon to configure what the assistant is allowed to do.

* **Search** — pick the **folder to search contacts in** and the **search field** holding the phone number. The assistant looks contacts up by phone in that folder.
* **Create** — pick the **folder to create contacts in**, then set up **field mapping**: for each assistant parameter, choose the NetHunt field it writes to, its type, and whether it's required.

Field mapping is what makes contact creation work. If a required NetHunt field has no mapped parameter, the contact won't be created.

## Troubleshooting [#troubleshooting]

| Error                                 | Cause                                             | Fix                                                                                                                                                                                          |
| ------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_API_KEY`                     | Key mistyped or copied with spaces                | Re-copy the token from NetHunt > Settings > Apps and other integrations.                                                                                                                     |
| Authentication fails with a valid key | Email doesn't match the account that owns the key | The email and the API key must belong to the same NetHunt account.                                                                                                                           |
| `TOKEN_REVOKED` (401)                 | An admin rotated or revoked the key               | Generate a fresh key in NetHunt and reconnect in HAPP.                                                                                                                                       |
| `RATE_LIMITED` (429)                  | NetHunt's API rate limit hit                      | Wait 1–2 minutes and retry. If it keeps happening, [contact support](https://happ.tools/contacts) — we can throttle requests on our side.                                                    |
| Contacts aren't being created         | Folder or mapping misconfigured                   | Check three things, in order: a create folder is selected in **Settings**; every required NetHunt field has a mapped parameter; the mapped fields are still active in NetHunt, not archived. |

Still stuck? [Contact support](https://happ.tools/contacts) with the error text and we'll point at the exact fix.

## Disconnect and reconnect [#disconnect-and-reconnect]

**To disconnect:** open **Integrations** > **NetHunt**, click **Disconnect** next to the connected workspace, and confirm.

After disconnecting:

* New contacts from chat stop being sent to NetHunt.
* Existing contacts in NetHunt stay untouched.
* The assistant keeps working in chat — only the NetHunt sync stops.
* The API key is **not** revoked in NetHunt. Revoke it there separately if you need to.

**To reconnect:** open **Integrations** > **NetHunt**, click **Connect** and enter the email and API key again.

Preserved after reconnecting: folder selection, field mapping, the assistant-to-workspace binding, and analytics for the integration.

## Next [#next]

* [CRM](/docs/integrations/crm) — all CRM integrations
* [Tools](/docs/tools) — call the CRM during conversations
* [Integrations](/docs/integrations) — the full catalog