> ## 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. # Create thread > Create a new active thread with a prospect ## OpenAPI ````yaml POST /threads openapi: 3.1.1 info: title: Inbox API version: 1.0.0 description: >+ The Inbox API gives you full access to manage the following entities in your team: - **Threads**: DM conversations on X - **Account links**: X accounts connected to your team - **Members**: users who can access the team - **Prospects**: external profiles on X - **Tags**: labels for prospects - **Statuses**: pipeline statuses for prospects - **Lists**: collections of leads with custom columns and import jobs - **Campaigns**: automated multi-step DM sequences ## A quick note on IDs Inbox stores two types of IDs for objects that relate to X: - `id` — The Inbox ID, which is the ID of the Inbox object - `platformId` — The original X 'platform' ID, which is the ID of the X user, conversation, etc. Throughout the API, you'll see instances where multiple IDs are present. `platformId` is always the original X ID. ## Helpful X URLs You can use platform IDs to construct direct links to X: - **User profile**: `https://x.com/i/user/{platformId}` — This is the most reliable way to link to a user since it uses their immutable ID rather than their username, which can change. - **User by username**: `https://x.com/{username}` — Note that usernames can change, so this link may break if the user updates their handle. - **Tweet/Post**: `https://x.com/anyusername/status/{tweetId}` — The username in the URL is ignored by X; only the tweet ID matters. You can use any string in place of the username and the link will still work. - **DM conversation**: `https://x.com/i/chat/{conversationPlatformId}` — The conversation ID is formatted as `{smallerUserId}:{largerUserId}`, where the two participant user IDs are sorted numerically (smaller ID first). ## Encoding objects and arrays in query params Inbox's API uses bracket notation to denote objects and arrays. ### Objects For an endpoint that accepts a `cursor` parameter for instance, with the cursor object being ```json { id: "l44e15irdq4db30i77cgphhx", timestamp: "2025-11-10T18:03:16.000Z" } ``` The URL search params would be encoded as: ```txt ?cursor[id]=l44e15irdq4db30i77cgphhx&cursor[timestamp]=2025-11-10T18:03:16.000Z ``` ### Arrays For an endpoint that accepts an `ids` parameter for instance, with the value being ```json ["1", "2", "3"] ``` there are three options: 1. Repeat the parameter for each value: ```txt ?ids=1&ids=2&ids=3 ``` 2. Append `[]` to explicitly denote an array (useful if there's only one value): ```txt ?ids[]=1&ids[]=2&ids[]=3 ``` 3. Append `[number]` to denote the array index. This option is the most flexible and allows for reordering and skipping values: ```txt ?ids[0]=1&ids[1]=2&ids[2]=3 ``` summary: >- The Inbox API gives you full access to manage the following entities in your team. servers: - url: https://inboxapp.com/api/v1 security: [] tags: - name: Teams description: >- Teams are shared workspace for members to view and manage account links, tags, statuses, campaigns, conversations, and more. - name: Threads description: >- Threads represent conversations between an account linked to your team and a prospect on Twitter. - name: Messages description: |- Messages are the individual messages sent in a thread. - name: Account Links description: |- Account links represent X accounts connected to your team. - name: Members description: |- Members are Inbox users who can access the team. - name: Prospects description: |- Prospects represent external profiles on X. - name: Tags description: |- Tags are labels for prospects. - name: Statuses description: >- Statuses are used to track the deal stage or any fixed state for a prospect. - name: Colors description: >- Get predefined color options that can be used when creating or updating tags and statuses. - name: Lists description: >- Lists are collections of leads that you can organize, filter, and use as targeting sources for campaigns. - name: List columns description: >- Custom columns defined on a list. Each column stores a text value per lead and can be used as merge variables in campaign messages. - name: Leads description: >- Leads are prospects that belong to a list. Each lead has the full prospect profile, CRM context (tags, status, notes), and list-specific custom column data. - name: Import jobs description: >- Import jobs populate lists from various sources including CSV files, X followers, tweet engagements, and X lists. Poll the job status endpoint to track progress. - name: Campaigns description: >- Campaigns are automated multi-step DM sequences sent to leads via your linked X accounts. A campaign pulls its leads from your existing lists using **lead rules** — attach lists to automatically sync leads into the campaign, and optionally exclude lists (e.g. a "Do Not Contact" list) to avoid messaging certain people. Leads can also be added directly or imported in bulk. Each campaign has a **sequence** of steps — messages, delays, and tweet interactions — that run for every lead. Messages support variables for personalization: use the built-in `first-name` variable or create **custom columns** on the campaign to store per-lead data like company name or role. **Automations** let you trigger actions when certain events occur, such as applying a tag or setting a status when a prospect replies. Configure a sending schedule and hourly message rate, then enable the campaign to start sending. paths: /threads: post: tags: - Threads summary: Create thread description: Create a new active thread with a prospect operationId: threads.create requestBody: required: true content: application/json: schema: type: object properties: externalPlatformId: type: string description: >- The platform ID of the prospect. Must be provided if externalId is not provided. examples: - '1234567890' externalId: type: string pattern: ^[0-9a-z]+$ description: >- The Inbox external ID of the prospect. Must be provided if externalPlatformId is not provided. accountLinkId: type: string pattern: ^[0-9a-z]+$ description: >- The account link ID to associate with this thread. This determines which connected account the thread belongs to. required: - accountLinkId responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Thread' components: schemas: Thread: type: object properties: id: type: string pattern: ^[0-9a-z]+$ description: The ID of the thread. examples: - df6jbw4h36... platform: enum: - twitter description: The platform this thread belongs to. examples: - twitter platformId: type: string description: The platform ID of the conversation. examples: - '1234567890' done: type: boolean description: Whether the thread has been archived or not. examples: - true assigneeId: anyOf: - type: string pattern: ^[0-9a-z]+$ - type: 'null' description: The ID of the member assigned to the thread. examples: - df6jbw4h36... lastMessageTimestamp: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: The timestamp of the last message in the thread. examples: - '2025-08-22T12:00:00.000Z' computedSortTimestamp: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: >- The timestamp of the last message in the thread or the creation date if no messages have been sent. examples: - '2025-08-22T12:00:00.000Z' createdAt: type: string format: date-time x-native-type: date description: The timestamp of when the thread was created in Inbox. examples: - '2025-08-22T12:00:00.000Z' status: enum: - active - idle description: >- Idle threads are hidden from the main inbox, i.e. when previewing a profile using 'Quick peek' examples: - active variant: enum: - unencrypted - xChat description: >- Will be set to "unencrypted" by default for new conversations until both parties have exchanged messages. Once each party has sent at least one message, the conversation transitions to "xChat" (encrypted). examples: - unencrypted accountLinkId: type: string pattern: ^[0-9a-z]+$ description: The ID of the account link associated with this thread. examples: - df6jbw4h36... isSyncing: type: boolean description: >- Whether the thread is currently syncing data from Twitter to load all messages. examples: - false isRequest: type: boolean description: Whether this conversation is a message request. examples: - false typingIndicatorsEnabled: anyOf: - type: boolean - type: 'null' description: >- Whether typing indicators are enabled for this thread. If set to null, will use the team default setting. examples: - true lastMessage: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-z]+$ description: >- The ID of the last message in the thread. This is the message that will be displayed in the thread preview. examples: - df6jbw4h36... content: type: string description: The content of the last message in the thread. examples: - Hey, I'm reaching out from Acme Agency... authorId: type: string description: >- Points to either the accountLinkId or the externalId of the thread. May be a cuid2 or a legacy external ID. examples: - df6jbw4h36... createdAt: type: string format: date-time x-native-type: date description: The timestamp of when the last message was created in Inbox. examples: - '2025-08-22T12:00:00.000Z' userId: anyOf: - type: string pattern: ^[0-9a-z]+$ - type: 'null' description: >- The ID of the Inbox user who sent the last message in the thread. Note that this is not a member ID. examples: - df6jbw4h36... campaignId: anyOf: - type: string pattern: ^[0-9a-z]+$ - type: 'null' description: >- The ID of the campaign that sent the last message in the thread. This is only set if the last message was sent by a campaign. examples: - df6jbw4h36... required: - id - content - authorId - createdAt - userId - campaignId - type: 'null' prospect: allOf: - $ref: '#/components/schemas/Prospect' - type: object properties: context: type: object properties: tags: type: array items: type: string pattern: ^[0-9a-z]+$ description: The tag IDs attached to this prospect. examples: - - df6jbw4h36... statusId: anyOf: - type: string pattern: ^[0-9a-z]+$ - type: 'null' description: The status ID of the prospect. examples: - df6jbw4h36... valuation: anyOf: - type: number - type: 'null' description: The valuation of the prospect. examples: - 599 notes: anyOf: - type: string - type: 'null' description: Notes attached to the prospect. examples: - This prospect is a potential customer. required: - tags - statusId - valuation - notes required: - context required: - id - platform - platformId - done - assigneeId - lastMessageTimestamp - computedSortTimestamp - createdAt - status - variant - accountLinkId - isSyncing - isRequest - typingIndicatorsEnabled - lastMessage - prospect Prospect: type: object properties: platform: enum: - twitter description: The social platform where this prospect's profile exists. examples: - twitter platformId: type: string description: >- The platform's native user ID. For Twitter, this is the numeric user ID. This is the primary identifier for cross-platform operations. examples: - '1566123362161725440' externalId: anyOf: - type: string - type: 'null' description: >- Unique identifier for this prospect in the Inbox system. Null if the prospect hasn't been imported yet. examples: - l44e15irdq4db30i77cgphhx documentId: anyOf: - type: number - type: 'null' description: >- Search index identifier for fast lookups. Null if the prospect isn't indexed yet. examples: - 858224163 displayName: type: string description: >- The user's display name as shown on their profile. For businesses, typically the company name. examples: - Inbox username: type: string description: >- The unique handle/username on the platform, without the @ symbol. Always lowercase for Twitter. examples: - InboxApp_ handle: type: string description: >- The username with @ symbol prefix, ready for display in UI. Computed from username. examples: - '@InboxApp_' image: anyOf: - type: string - type: 'null' description: >- Profile picture URL as provided by platform. May contain size suffixes or be lower quality. Prefer imageNormalized for display. examples: - >- https://pbs.twimg.com/profile_images/1954360649393295360/rwp-vVt6.jpg imageNormalized: anyOf: - type: string - type: 'null' description: >- Profile picture URL normalized to highest quality available. Size suffixes removed. Prefer this over image for display. examples: - >- https://pbs.twimg.com/profile_images/1954360649393295360/rwp-vVt6.jpg bio: anyOf: - type: string - type: 'null' description: The user's profile bio/description text. examples: - >- Social Selling CRM Close deals faster, stay organized, and never miss an opportunity. Starting with X location: anyOf: - type: string - type: 'null' description: >- Freeform location string as entered by user. Not normalized or geocoded. examples: - San Francisco, CA profileUrl: type: string description: Direct link to view this profile on the platform. examples: - https://x.com/InboxApp_ websiteUrl: anyOf: - type: string - type: 'null' description: External website URL the user provided in their profile, if any. examples: - https://inboxapp.com websiteDomain: anyOf: - type: string - type: 'null' description: Domain extracted from websiteUrl for quick filtering and grouping. examples: - inboxapp.com verified: enum: - none - verified - business - government description: >- Verification badge status: none (no badge), verified (blue checkmark), business (gold badge), or government (gray badge). examples: - business profileType: enum: - personal - business - government description: >- Account type classification: personal (individual), business (organization), or government (official agency). examples: - business isProtected: type: boolean description: >- Whether the account is private/protected. For Twitter: protected tweets enabled. Private accounts require approval to follow. examples: - false followerCount: type: number description: Number of users following this account. examples: - 3068 followingCount: type: number description: Number of users this account follows. examples: - 288 postCount: type: number description: >- Total content posted by this account. For Twitter: tweet count. For Instagram: post count. examples: - 836 engagementCount: anyOf: - type: number - type: 'null' description: >- Platform-specific engagement metric. For Twitter: likes/favorites given by user. May be null if platform doesn't provide this. examples: - 2613 listedCount: anyOf: - type: number - type: 'null' description: >- How many Twitter lists this profile appears on. Useful metric for influence. Null for non-Twitter platforms. examples: - 18 platformCreatedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: >- When the account was created on the platform. Null if platform doesn't provide this data. examples: - '2022-09-03T17:58:06.000Z' firstSeenAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: >- When this prospect was first added to Inbox. Useful for tracking relationship timeline. examples: - '2024-07-09T14:08:49.000Z' lastUpdatedAt: type: string format: date-time x-native-type: date description: Most recent update timestamp for any data about this prospect. examples: - '2025-11-10T18:03:16.000Z' lastEnrichedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: >- When fresh data was last fetched from the platform API. Use this to determine if data needs refresh. examples: - '2025-11-10T18:03:16.000Z' lastActiveAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' description: >- Last time the profile was active on the platform (posted, liked, or engaged). Platform-dependent availability. examples: - '2025-11-10T12:00:00.000Z' source: enum: - cached - indexed - live - merged description: >- Data source: cached (stored), indexed (searchable), live (real-time from platform), or merged (combined sources). examples: - cached isFresh: type: boolean description: >- Indicates if data was updated within the last 7 days. Fresh data is current and reliable. examples: - true isStale: type: boolean description: >- Indicates if data hasn't been updated in over 30 days. Stale data may need refreshing for accuracy. examples: - false confidence: type: number minimum: 0 maximum: 1 description: >- Confidence score for data accuracy (0-1). Higher values indicate more recent and reliable data. 1.0 = real-time, 0.8+ = recent, below 0.5 = potentially outdated. examples: - 0.85 accountStatus: enum: - active - suspended - notFound description: >- Account status on the platform. 'active' = accessible, 'suspended' = platform confirmed suspension, 'notFound' = deleted or deactivated. examples: - active platformData: type: object properties: isVerifiedBlue: type: boolean description: Standard Twitter blue checkmark verification badge. examples: - false isVerifiedGold: type: boolean description: >- Gold verification badge indicating a business/brand account on Twitter. examples: - true isVerifiedGray: type: boolean description: >- Gray verification badge indicating a government/official account on Twitter. examples: - false professionalCategory: anyOf: - type: string - type: 'null' description: >- Professional category ID if the account has set one. Maps to categories like Technology, Media, Education, etc. examples: - '986' urlEntities: type: array items: type: object properties: url: type: string description: Shortened t.co URL as it appears in the tweet text. examples: - https://t.co/abc123 expandedUrl: type: string description: Full expanded URL that the t.co link redirects to. examples: - https://inboxapp.com displayUrl: type: string description: >- Human-readable display text for the URL (typically domain + path). examples: - inboxapp.com indices: type: array prefixItems: - type: number - type: number description: >- Start and end character indices where this URL appears in the bio text. examples: - - 0 - 23 required: - url - expandedUrl - displayUrl - indices description: >- Parsed URL entities from the bio text with expanded and display URLs. examples: - [] bannerUrl: anyOf: - type: string - type: 'null' description: >- Profile banner/header image URL (typically 1500x500px). Null if no banner is set. examples: - >- https://pbs.twimg.com/profile_banners/1566123362161725440/1753273968 tweetsCount: type: number description: Total number of tweets posted by this account (all-time count). examples: - 836 favoritesCount: type: number description: >- Total number of likes/favorites this user has given to other tweets. examples: - 2613 rawData: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- Full Twitter API user object for backward compatibility and advanced use cases. Null if not available from the data source. required: - isVerifiedBlue - isVerifiedGold - isVerifiedGray - professionalCategory - urlEntities - bannerUrl - tweetsCount - favoritesCount - rawData required: - platform - platformId - externalId - documentId - displayName - username - handle - image - imageNormalized - bio - location - profileUrl - websiteUrl - websiteDomain - verified - profileType - isProtected - followerCount - followingCount - postCount - engagementCount - listedCount - platformCreatedAt - firstSeenAt - lastUpdatedAt - lastEnrichedAt - lastActiveAt - source - isFresh - isStale - confidence - accountStatus - platformData ````