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

# Account links

> Managing connected X accounts in Inbox

## Overview

Account links represent X (Twitter) accounts connected to your Inbox team. Each account link enables you to send and receive DMs through that account.

## List account links

Retrieve all connected accounts:

<CodeGroup>
  ```typescript account-links.ts theme={null}
  const { data: accountLinks } = await client.get("/account-links");

  console.log(`${accountLinks.length} connected account(s)`);

  accountLinks.forEach((account) => {
    console.log(`@${account.username} (${account.id})`);
  });
  ```

  ```bash cURL theme={null}
  curl https://inboxapp.com/api/v1/account-links \
    -H "Authorization: Bearer $INBOX_API_TOKEN"
  ```
</CodeGroup>

**Response:**

```json theme={null}
[
  {
    "id": "df6jbw4h36qm5d9iu2sgn7kx",
    "platform": "twitter",
    "platformId": "1566123362161725440",
    "name": "Acme Corp",
    "username": "acmecorp",
    "image": "https://pbs.twimg.com/profile_images/.../photo.jpg",
    "createdAt": "2024-06-01T12:00:00.000Z",
    "status": "active",
    "syncedAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": "g7ht2kw9xr5m8fp3yjnbqvce",
    "platform": "twitter",
    "platformId": "1876543210987654321",
    "name": "Acme Support",
    "username": "acmesupport",
    "image": "https://pbs.twimg.com/profile_images/.../photo.jpg",
    "createdAt": "2024-08-01T09:00:00.000Z",
    "status": "active",
    "syncedAt": "2025-01-14T08:00:00.000Z"
  }
]
```

<Note>
  `GET /account-links` returns a flat array, not a wrapped object. The same
  applies to `GET /members`, `GET /tags`, and `GET /statuses`.
</Note>

### Key fields

| Field        | Description                                                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `id`         | Inbox account link ID — use this for all API operations                                                                      |
| `platform`   | Always `"twitter"` for now                                                                                                   |
| `platformId` | The X numeric user ID                                                                                                        |
| `username`   | X handle without `@`                                                                                                         |
| `image`      | Profile picture URL                                                                                                          |
| `status`     | `"active"`, `"offline"` (X signed out your account), or `"paused"` (team scheduled for deletion or other rare circumstances) |
| `syncedAt`   | When this account completed its first full sync. `null` if sync hasn't finished yet                                          |

## Using account links

### Send messages from specific accounts

Specify which account to send from using `accountLinkId`:

```typescript theme={null}
const { data: accountLinks } = await client.get("/account-links");
const salesAccount = accountLinks.find((a: any) => a.username === "acmecorp");

await client.post("/threads/messages", {
  externalPlatformId: "1876543210987654321",
  accountLinkId: salesAccount.id,
  content: "Hi! Reaching out from our sales team.",
});
```

### Filter threads by account

View conversations for specific accounts using `accountLinkIds`:

```typescript theme={null}
const { data } = await client.get("/threads", {
  params: {
    "accountLinkIds[0]": "df6jbw4h36qm5d9iu2sgn7kx",
  },
});

console.log(`${data.threads.length} threads for this account`);
```

### Lookup threads by account

Check if a thread exists for a specific account–prospect pair:

```typescript theme={null}
const { data: thread } = await client.get("/threads/lookup", {
  params: {
    externalPlatformId: "1876543210987654321",
    accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
  },
});

if (thread) {
  console.log("Thread exists:", thread.id);
} else {
  console.log("No existing thread");
}
```

## Multi-account patterns

### Account selection logic

Choose the appropriate account based on context:

```typescript theme={null}
interface AccountSelector {
  accountLinkId: string;
  condition: (prospect: any) => boolean;
}

const accountRules: AccountSelector[] = [
  {
    accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
    condition: (prospect) => prospect.followerCount >= 100000,
  },
  {
    accountLinkId: "g7ht2kw9xr5m8fp3yjnbqvce",
    condition: () => true,
  },
];

function selectAccount(prospect: any): string {
  for (const rule of accountRules) {
    if (rule.condition(prospect)) return rule.accountLinkId;
  }
  return accountRules[accountRules.length - 1].accountLinkId;
}
```

### Cross-account thread check

Check if you have any existing thread with a prospect across all accounts:

```typescript theme={null}
async function findAnyThread(prospectPlatformId: string) {
  const { data: accountLinks } = await client.get("/account-links");

  for (const account of accountLinks) {
    const { data: thread } = await client.get("/threads/lookup", {
      params: {
        externalPlatformId: prospectPlatformId,
        accountLinkId: account.id,
      },
    });

    if (thread) {
      return { thread, accountLink: account };
    }
  }

  return null;
}

const existing = await findAnyThread("1876543210987654321");
if (existing) {
  console.log(`Found thread via @${existing.accountLink.username}`);
}
```

## ID types

<Warning>
  Account links have two ID types. Use the correct one:

  | Property            | Example                      | Use for            |
  | ------------------- | ---------------------------- | ------------------ |
  | `id` (Inbox ID)     | `"df6jbw4h36qm5d9iu2sgn7kx"` | All API operations |
  | `platformId` (X ID) | `"1566123362161725440"`      | Reference only     |

  ```typescript theme={null}
  // Correct: Use Inbox ID
  await client.get("/threads", {
    params: { "accountLinkIds[0]": account.id },
  });

  // Wrong: Using platform ID
  await client.get("/threads", {
    params: { "accountLinkIds[0]": account.platformId },
  });
  ```
</Warning>

## Connecting new accounts

<Info>
  Account links are connected through the Inbox dashboard, not the API. To add a new X account:

  1. Go to [inboxapp.com](https://inboxapp.com)
  2. Navigate to **Settings → Accounts**
  3. Make sure you have the [Chrome extension installed](https://chromewebstore.google.com/detail/inbox/manipndiogdfeenejomojogbbcbenioe)
  4. Click **Open X** and select the account to link

  The new account will then appear in API responses.
</Info>

## Related endpoints

<CardGroup cols={2}>
  <Card title="List account links" icon="list-tree" href="/api-reference/account-links/list-account-links">
    GET /account-links
  </Card>

  <Card title="List threads" icon="list-tree" href="/api-reference/threads/list-threads">
    Filter by accountLinkIds
  </Card>

  <Card title="Lookup thread" icon="search" href="/api-reference/threads/lookup-thread">
    Find thread by account + prospect
  </Card>

  <Card title="Quick send" icon="send" href="/api-reference/messages/quick-send-message">
    Send from specific account
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Team setup" icon="users" href="/configuration/team-setup">
    Configure team members
  </Card>

  <Card title="Managing threads" icon="messages-square" href="/guides/managing-threads">
    Work with conversations
  </Card>

  <Card title="Working with messages" icon="message-circle" href="/guides/messages">
    Send and receive messages
  </Card>

  <Card title="Quick start" icon="rocket" href="/quickstart">
    Send your first message
  </Card>
</CardGroup>