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

# Quick start

> Send your first DM through the API in five minutes

This guide sends a DM from one of your connected accounts to a lead, then reads the reply.

## Before you start

* A connected X or LinkedIn account in your workspace.
* A lead list with at least one lead.
* An API key. See [Authentication](https://docs.reachhunt.ai/developer-api/authentication.md).

Save the key in your terminal so the commands below can use it:

```bash theme={"system"}
export REACHHUNT_API_KEY="YOUR_API_KEY"
```

## Send your first DM

**1. Pick the account to send from**

List your connected accounts:

```bash theme={"system"}
curl "https://api.reachhunt.ai/api/v1/accounts" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY"
```

Keep the `id` of an account whose `status` is `connected`:

```json theme={"system"}
{
  "status": true,
  "data": [
    {
      "id": "4f1c9a2e-6b7d-4c3a-9e51-0a8b7c6d5e4f",
      "platform": "x",
      "handle": "acmecorp",
      "status": "connected"
    }
  ],
  "error": null
}
```

**2. Pick a lead**

List your lead lists, then the leads in one of them:

```bash theme={"system"}
curl "https://api.reachhunt.ai/api/v1/leads" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY"

curl "https://api.reachhunt.ai/api/v1/leads/LEAD_LIST_ID/prospects" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY"
```

Keep the `id` of a lead on the same network as your account.

**3. Find or start the conversation**

```bash theme={"system"}
curl -X POST "https://api.reachhunt.ai/api/v1/conversations/get-or-create" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "ACCOUNT_ID", "prospectId": "LEAD_ID"}'
```

Keep `conversation.conversationId`. If you have never messaged this person, ReachHunt creates a draft that becomes a real conversation when you send the first message.

Check `canSend` before you send. When it is `false`, `blockedReason` says why, such as `peer_unreachable`.

**4. Send the message**

```bash theme={"system"}
curl -X POST "https://api.reachhunt.ai/api/v1/conversations/CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "ACCOUNT_ID", "text": "Hi Jane, loved your post on outbound. Open to a quick chat?"}'
```

URL-encode the conversation ID in the path. X conversation IDs contain `:`, which becomes `%3A`. The response has the new `messageId`.

**5. Read the reply**

```bash theme={"system"}
curl "https://api.reachhunt.ai/api/v1/conversations/CONVERSATION_ID/messages?accountId=ACCOUNT_ID" \
  -H "Authorization: Bearer $REACHHUNT_API_KEY"
```

Messages come newest first. `fromMe` is `false` on the messages the lead sent.

> [!TIP]
>
> Instead of checking for replies, add a webhook for `message.received`. ReachHunt sends each new message to your server as it arrives.

## Next steps

> **[Core concepts](https://docs.reachhunt.ai/developer-api/core-concepts.md)**
>
> How accounts, conversations, leads and campaigns fit together.

> **[Receiving webhooks](https://docs.reachhunt.ai/webhooks/receiving.md)**
>
> Get replies and other events on your server.

> **[Errors](https://docs.reachhunt.ai/developer-api/errors.md)**
>
> What each status code and message means.

> **[Rate limits](https://docs.reachhunt.ai/developer-api/rate-limits.md)**
>
> How much each account can send.


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