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

# Go live

> The end-to-end sequence to connect a custom CRM — who does what, the real HunterAI endpoints, and what does not work yet.

Connecting a custom CRM involves three parties. This page names who performs each step.

<CardGroup cols={3}>
  <Card title="Customer developer" icon="code">
    You. Implements the endpoints and issues the token.
  </Card>

  <Card title="Business owner" icon="user-tie">
    The HunterAI account owner for your company. Creates the connection.
  </Card>

  <Card title="HunterAI" icon="server">
    Runs the sync and surfaces the data.
  </Card>
</CardGroup>

## The sequence

<Steps>
  <Step title="Implement the required endpoints — customer developer">
    Build the four required endpoints — [`/pipelines`](/endpoints/pipelines),
    [`/users`](/endpoints/users), [`/contacts`](/endpoints/contacts),
    [`/leads`](/endpoints/leads) — and any optional ones you want
    ([`/events`](/endpoints/events), [`/tasks`](/endpoints/tasks),
    [`/calls`](/endpoints/calls)). Return `404` for optional endpoints you skip. Work
    through the [Conformance checklist](/guides/conformance-checklist) before moving on.
  </Step>

  <Step title="Issue a token and decide a rate limit — customer developer">
    Create a **read-only** Bearer token scoped to those endpoints (see
    [Authentication](/authentication)) and decide the **requests-per-second** rate your API
    can sustain (see [Rate limits](/rate-limits)). Hand the business owner: the **base URL**,
    the **token**, and the **rate**.
  </Step>

  <Step title="Create the connection in HunterAI — business owner">
    The business owner registers the connection through the HunterAI API (below), then runs
    the test call. Only the account **owner** may do this — the ROP/MOP roles get `403`.
  </Step>

  <Step title="First sync — HunterAI">
    HunterAI runs a full pull in the background, then resumes incrementally from the
    watermark on later runs. Once it completes, your data appears in the HunterAI dashboards
    and funnels for that connection.
  </Step>
</Steps>

## The HunterAI onboarding API

These endpoints live on HunterAI (not on your CRM) and are called by the **business owner**,
authenticated as the workspace owner. All are under `/api/v1`.

### Create the connection

```http theme={null}
POST /api/v1/crm/custom/connections HTTP/1.1
Host: api.hunterai.uz
Authorization: Bearer <business owner's HunterAI session token>
Content-Type: application/json

{
  "base_url": "https://crm.example.uz/api/hunterai/v1",
  "token": "sk_live_9f2c…",
  "rate_limit": 10,
  "sync_since": "2025-01-01T00:00:00+05:00",
  "trigger_sync": true
}
```

| Body field     | Type        | Required     | Meaning                                                                                     |
| -------------- | ----------- | ------------ | ------------------------------------------------------------------------------------------- |
| `base_url`     | string      | **Required** | Root of your API. A trailing slash is stripped.                                             |
| `token`        | string      | **Required** | The read-only Bearer token. Stored encrypted; never returned.                               |
| `rate_limit`   | integer ≥ 1 | Optional     | Requests per second. Omit to use the default (5/s).                                         |
| `sync_since`   | ISO-8601    | Optional     | Start date for the first full sync. Omit to default to 1 January of the current year.       |
| `trigger_sync` | boolean     | Optional     | `true` queues a full sync immediately after the connection is created. Defaults to `false`. |

```json 201 Created theme={null}
{
  "id": "b3f1c8e2-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "business_account_id": "a1b2c3d4-…",
  "crm_type": "custom",
  "base_url": "https://crm.example.uz/api/hunterai/v1",
  "rate_limit": 10,
  "sync_since": "2025-01-01T00:00:00+05:00",
  "created_at": "2025-07-24T09:00:00Z",
  "updated_at": "2025-07-24T09:00:00Z"
}
```

<Note>
  The token is **never** echoed back in any response. If `trigger_sync` is `true` but the
  sync queue is temporarily down, the connection is still created — the sync just is not
  queued, and can be re-triggered later.
</Note>

### Test the connection

Runs a live check against your `/pipelines` (first page only) and reports reachability and
auth.

```http theme={null}
POST /api/v1/crm/custom/connections/{connection_id}/test HTTP/1.1
Host: api.hunterai.uz
Authorization: Bearer <business owner's HunterAI session token>
```

```json 200 OK theme={null}
{
  "reachable": true,
  "authenticated": true,
  "detail": "Connection successful.",
  "pipelines_found": 1
}
```

| Result field      | Meaning                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `reachable`       | Whether HunterAI could reach your API at all (DNS, TLS, connectivity). |
| `authenticated`   | Whether the token was accepted (`false` on `401`).                     |
| `detail`          | Human-readable outcome, including the failure reason if any.           |
| `pipelines_found` | Number of pipelines on the first page (present on success).            |

### Manage the connection

| Method & path                               | Purpose                                                                                                                    |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v1/crm/custom/connections`        | List this workspace's custom connections.                                                                                  |
| `GET /api/v1/crm/custom/connections/{id}`   | Fetch one connection.                                                                                                      |
| `PATCH /api/v1/crm/custom/connections/{id}` | Update `base_url`, `token`, `rate_limit`, or `sync_since`. Used to [rotate the token](/authentication#rotating-the-token). |

<Note>
  Lookups are tenant-scoped: a connection is only visible to the workspace that owns it.
  Another workspace requesting the same id gets `404`.
</Note>

## What does not work yet

<Warning>
  **CRM managers are not automatically linked to HunterAI logins for a custom source.**

  Your managers from [`/users`](/endpoints/users) are ingested and used to attribute deals,
  tasks, and calls — but they are **not** turned into HunterAI user accounts. This is a
  **deliberate security decision**: a custom source is treated as untrusted, so HunterAI
  does not auto-provision logins from its user list (unlike the amoCRM integration, which
  auto-links managers by email).

  **Consequence:** until invitation-based linking ships, the following are **unavailable**
  for a custom connection:

  * per-manager dashboards,
  * manager-scoped data access,
  * individual AI coaching per manager.

  Workspace-level analytics (funnels, revenue, totals) work fully. Only the per-manager
  features above wait on linking. There is no committed date for it; do not build assuming
  per-manager logins exist today.
</Warning>