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

# Core concepts

> How your workspace, accounts, conversations, leads and campaigns fit together

The API works on one workspace: the one your API key belongs to. Everything in it starts from the X and LinkedIn accounts you connect.

## How it fits together

```txt theme={"system"}
Workspace
├── Accounts             your connected X and LinkedIn accounts
│   ├── Conversations    one per account and person
│   │   └── Messages
│   └── Requests         message requests and invitations waiting for an answer
├── Lead lists           people you collect from X and LinkedIn
│   └── Leads
├── Campaigns            message sequences sent from accounts to lead lists
├── AI agents            reply in conversations for the accounts they are assigned to
├── Templates            saved messages
└── Tags and statuses    labels and pipeline stages for people
```

## Workspace

Your API key decides the workspace, so no path or parameter names one. To work with another workspace, create a key in that workspace. Your teammates are its members, and the ones you can assign conversations to are its assignees.

## Accounts

An account is an X or LinkedIn account connected to your workspace. You connect accounts in the ReachHunt app with the [ReachHunt extension](https://chromewebstore.google.com/detail/reachhunt/fkcjcmlojmeebgpgkmlmmmeakbhdoffe), not through the API.

An account's `status` is `connected`, or `needs_reauth` when it must be connected again in ReachHunt before it can send. Each account has its own [sending limits](https://docs.reachhunt.ai/developer-api/rate-limits.md).

## Conversations and messages

A conversation is between one connected account and one person. Its ID is `conversationId`, and most conversation and message calls also take the `accountId`. URL-encode the conversation ID in paths, because X IDs contain `:`.

[Find or start conversation](https://docs.reachhunt.ai/api-reference/conversations/find-or-start-conversation.md) returns the conversation with a person. When there is none yet, it creates a draft that becomes a real conversation when you send the first message.

Each message has `fromMe`, which is `true` when your account sent it. `sentBy` says who on your side sent it: a teammate, a campaign or an AI agent.

Requests are message requests and connection invitations waiting for an answer on one account.

## Leads and lead lists

A lead list collects people from one network, so it has a `platform`. Imports into a list run as jobs that you can follow, pause or stop.

A lead is a person in your lead lists. Request bodies call its ID `prospectId`.

A person's tags, status, note and deal value belong to the person, not to one conversation or list. Set them from the conversation or from the lead, and both show the change.

## Campaigns

A campaign sends a sequence of messages from one or more accounts to the people in its lead lists. It starts as a `draft`, runs as `running`, can be `paused` and resumed, and ends as `completed` or `stopped`. Each person a campaign reaches is one of its targets.

## AI agents

An AI agent replies in conversations for the accounts it is assigned to. Through the API you can list, pause, resume and delete agents. You create and train them in the ReachHunt app.

## Tags and statuses

Tags are labels, and a person can have many. Statuses are pipeline stages, and a person is in one at most, shown by `statusId`. Create both in the app or through the API, then set them on people.

## IDs

| ID | What it is |
| - | - |
| `id`, `accountId`, `conversationId`, `prospectId` and the other IDs | ReachHunt's own IDs, always strings. Use them in paths and request bodies |
| `platformId` | The ID the network gives a person or an account. It always comes with a `platform` |

## Platforms

`platform` is `x` or `linkedin`. Some fields only apply on one network. For example, a profile's `headline` and `connections` are LinkedIn only, and `tweets` is X only. A field that doesn't apply is `null`.

See [Response format](https://docs.reachhunt.ai/developer-api/response-format.md) for the conventions every response follows.


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