Skip to main content

​
Overview

The Inbox Enterprise API is built around managing conversations across messaging platforms. Understanding these core concepts will help you build effective integrations.
Multi-Platform Future: While the API currently supports X (Twitter) DMs, it’s designed to support Instagram, LinkedIn, TikTok, and WhatsApp in the future. The data model is platform-agnostic where possible.

​
Key Entities

​
Threads

A thread represents a DM conversation between one of your account links and a prospect. 
interface Thread {
  id: string;                    // Inbox thread ID
  platformId: string;            // Platform conversation ID
  accountLinkId: string;         // Which account this thread belongs to
  prospectId: string;            // The prospect you're messaging
  done: boolean;                 // Marked as complete?
  assignedToMemberId?: string;   // Assigned team member
  createdAt: string;
  updatedAt: string;
}
Key characteristics:
  • One thread per prospect-account pair
  • Can be assigned to team members
  • Can be marked as “done” to archive
  • Contains all messages in the conversation

​
Messages

Messages are individual DMs sent or received in a thread. 
interface Message {
  id: string;
  threadId: string;
  text: string;
  direction: 'inbound' | 'outbound';
  createdAt: string;
  platformId?: string;
}
Message directions:
  • inbound: Messages received from the prospect
  • outbound: Messages sent by your team

​
Prospects

A prospect represents an external user on a messaging platform. 
interface Prospect {
  id: string;                    // Inbox prospect ID
  platformId: string;            // Their X user ID
  platform: 'x';                 // Currently only 'x'
  platformUsername: string;      // Their @handle
  name?: string;
  description?: string;
  profileImageUrl?: string;
  verified: boolean;
  followersCount?: number;
  // ... other profile data
}
Important notes:
  • Prospects are shared across all account links in your team
  • Profile data is synced from the platform
  • You can add custom context (notes, valuation, tags, status)
An account link is a messaging platform account connected to your team. 
interface AccountLink {
  id: string;
  platformId: string;            // The X user ID
  platformUsername: string;      // @handle
  platform: 'x';                 // Platform type
  name: string;
  profileImageUrl?: string;
}
Use account links to:
  • Send messages from specific accounts
  • Filter threads by account
  • Manage multi-account workflows

​
Tags

Tags are flexible labels you can apply to prospects for organization. 
interface Tag {
  id: string;
  name: string;
  color: string;                 // Hex color code
  createdAt: string;
}
Common use cases:
  • Segment prospects (e.g., “Hot Lead”, “Customer”, “Partner”)
  • Track source (e.g., “Twitter Ad”, “Referral”)
  • Custom categorization

​
Statuses

Statuses represent a fixed pipeline stage or state for a prospect. 
interface Status {
  id: string;
  name: string;
  color: string;
  order: number;                 // Display order
  createdAt: string;
}
Key differences from tags:
  • A prospect can have multiple tags but only one status
  • Statuses are ordered (e.g., “New → Qualified → Customer”)
  • Ideal for sales pipelines

​
Members

Members are users on your team who can access the API and inbox. 
interface Member {
  id: string;
  email: string;
  name: string;
  role: string;
}
Use members for:
  • Assigning threads to specific team members
  • Filtering by assignee
  • Access control (coming soon)

​
The Dual ID System

Inbox uses two types of IDs for platform-related objects:

Inbox ID

Format: id Example: "thread_abc123"The internal Inbox database ID. Use this for all API operations.

Platform ID

Format: platformId Example: "123456789"The original ID from X (or other platforms). Use this to lookup or reference objects from the platform side.
When to use each: 
// Use Inbox IDs for API operations
await client.get(`/threads/${thread.id}/messages`);

// Use Platform IDs for lookups
await client.get('/threads/lookup', {
  params: { prospectPlatformId: '123456789' }
});

​
Thread States & Inbox Views

Threads can exist in different states, which determine their inbox view:

​
Default View

Active conversations that need attention.

​
No-Reply View

Threads where you sent the last message but haven’t received a reply.

​
Requests View

New message requests from prospects who haven’t messaged you before (or were previously deleted).

​
Archived View

Threads marked as “done” that are removed from active views. Example: Filtering by view 
// Get all active threads (default view)
const { data } = await client.get('/threads', {
  params: { inboxView: 'default' }
});

// Get message requests
const { data: requests } = await client.get('/threads', {
  params: { inboxView: 'requests' }
});

​
Entity Relationships

​
Pagination Pattern

Most list endpoints use cursor-based pagination: 
interface PaginatedResponse<T> {
  items: T[];
  nextCursor?: {
    id: string;
    timestamp: string;
  };
}
Iterating through pages: 
let cursor = undefined;

do {
  const { data } = await client.get('/threads', {
    params: { cursor, limit: 50 }
  });

  // Process data.threads
  processThreads(data.threads);

  cursor = data.nextCursor;
} while (cursor);
See the Pagination guide for details on encoding cursors in URLs.

​
Platform Field

All platform-related entities include a platform field: 
type Platform = 'x' | 'instagram' | 'linkedin' | 'tiktok' | 'whatsapp';
Currently: Only 'x' is supported. Future: Use this field to handle multi-platform scenarios: 
// Future-proof code
if (prospect.platform === 'x') {
  // X-specific logic
} else if (prospect.platform === 'instagram') {
  // Instagram-specific logic
}

​
Context Data

Prospects support custom context data for your workflow: 
interface ProspectContext {
  notes?: string;                // Custom notes
  valuation?: number;            // Deal value
  tags: string[];                // Array of tag IDs
  statusId?: string;             // Current status
  assignedToMemberId?: string;   // Assigned team member
  done: boolean;                 // Marked as complete
}
Updating context: 
await client.patch(`/prospects/${prospectId}/context`, {
  notes: 'Interested in Enterprise plan',
  valuation: 50000,
  tagIds: ['tag_abc', 'tag_xyz'],
  statusId: 'status_qualified'
});

​
Best Practices

When making API calls, use id (Inbox ID) not platformId. Only use platformId for lookups.
// ✅ Correct
await client.get(`/threads/${thread.id}/messages`);

// ❌ Wrong
await client.get(`/threads/${thread.platformId}/messages`);
Prospect profile data (followers, etc.) is synced periodically but may be stale. Don’t rely on it being real-time.
Tags for flexible categorization, statuses for pipeline stages. A prospect can have many tags but only one status.
Always implement pagination to avoid missing data or hitting response size limits.

​
Next Steps

Managing Threads

Learn thread operations and filtering

Working with Messages

Send and receive messages

Working with Prospects

Manage prospect data and context

Tags & Statuses

Organize with tags and pipeline stages