> ## 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. # Get leads > Get leads from a list with cursor-based pagination, optional filters, and sorting. Returns full prospect data including CRM context and custom column values. ## OpenAPI ````yaml get /lists/{listId}/leads 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: /lists/{listId}/leads: get: tags: - Leads summary: Get leads description: >- Get leads from a list with cursor-based pagination, optional filters, and sorting. Returns full prospect data including CRM context and custom column values. operationId: lists.leads.list parameters: - name: listId in: path required: true schema: type: string pattern: ^[0-9a-z]+$ description: The ID of the list. - name: cursor in: query required: false schema: type: string description: Pagination cursor. Omit to start from the beginning. allowEmptyValue: true allowReserved: true - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: >- Maximum number of leads to return per page. Defaults to 50, maximum 100. examples: - 50 allowEmptyValue: true allowReserved: true - name: search in: query required: false schema: type: string description: >- Free-text search query to filter leads by name, username, or bio. Can be combined with query filters. examples: - john allowEmptyValue: true allowReserved: true - name: query in: query required: false schema: type: object properties: filters: type: array items: type: object properties: type: enum: - and - or default: and description: >- Logical operator for combining filters in this group. Defaults to "and", meaning all filters must match. Use "or" to match leads that satisfy any filter in the group. examples: - and filters: type: array items: anyOf: - anyOf: - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: enum: - bio - location - notes operator: enum: - contains_any_of - not_contains_any_of - contains_all_of - not_contains_all_of value: type: array items: type: string required: - id - field - operator title: Keyword string filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: enum: - bio - name - screen_name - location - notes operator: enum: - contains - not_contains - contains_any_of - not_contains_any_of - contains_all_of - not_contains_all_of - starts_with - is - is_not - empty - not_empty value: type: string required: - id - field - operator title: String filter title: String filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: enum: - followers_count - friends_count - status_count - valuation operator: enum: - is - is_not - lt - gt - empty - not_empty value: type: number required: - id - field - operator title: Number filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: verification operator: enum: - is_any_of value: type: array items: enum: - none - blue - gold - gray required: - id - field - operator title: Verification filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: profile_type operator: enum: - is_any_of value: type: array items: enum: - personal - business - government required: - id - field - operator title: Profile type filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: account_status operator: enum: - is_any_of value: type: array items: enum: - active - suspended - deactivated required: - id - field - operator title: Account status filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: enum: - last_contacted_at - last_replied_at - account_created_at operator: enum: - date_after - date_before - date_on - date_between value: anyOf: - type: string - type: object properties: from: type: string to: type: string required: - from - to required: - id - field - operator title: Date filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: display_url operator: enum: - has_domain - starts_with - is - is_not - empty - not_empty value: type: string required: - id - field - operator title: Website filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: tag operator: enum: - include - do_not_include - include_all_of - include_any_of - exclude_if_any_of - exclude_if_all - tag_empty - tag_not_empty value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: Tag filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: status operator: enum: - status_is - status_is_not - status_is_any_of - status_empty - status_not_empty value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: Status filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: campaign operator: enum: - campaign_in - campaign_not_in - campaign_in_any_of - campaign_in_all_of - campaign_not_in_any_of - campaign_targeted - campaign_never_targeted value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: Campaign filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: assignee operator: enum: - assignee_is - assignee_is_not - assignee_is_any_of - assignee_empty - assignee_not_empty value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: Assignee filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: stage operator: enum: - stage_is - stage_is_not - stage_is_any_of value: type: array items: enum: - pending - assigned - ongoing - replied - unresponsive - failed - canceled required: - id - field - operator title: Stage filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: sending_account operator: enum: - sending_account_is - sending_account_is_not - sending_account_is_any_of value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: Sending account filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: reachable operator: enum: - reachable_by_any_of - reachable_by_all_of - reachable_only_by - reachable_not_by - reachable - unreachable value: type: array items: type: string required: - id - field - operator title: Reachable filter - type: object properties: id: type: string pattern: ^[0-9a-z]+$ field: const: list_membership operator: enum: - list_is_in - list_is_not_in - list_is_in_any_of - list_is_in_all_of - list_is_not_in_any_of value: type: array items: type: string pattern: ^[0-9a-z]+$ required: - id - field - operator title: List filter description: Array of individual filter conditions within this group. not: type: boolean description: >- When true, negates the entire filter group. A negated AND group matches leads that fail at least one condition. A negated OR group matches leads that fail all conditions. required: - filters description: >- Array of filter groups. Each group contains filters combined by its type (AND/OR). Multiple groups are combined with AND logic at the top level. required: - filters description: >- Structured filter query. Supports filtering by bio, name, username, location, followers count, following count, tweet count, verification status, website, profile type, valuation, tags, status, campaigns, assignee, reachability, list membership, account status, last contacted, last replied, account created date, and notes. Filters are organized into groups. Each group has a type ("and" or "or") that determines how its filters are combined. By default, all filters use AND logic — every condition must match. To use OR logic, set the group type to "or". Multiple groups at the top level are always combined with AND. style: deepObject explode: true allowEmptyValue: true allowReserved: true - name: sort in: query required: false schema: type: object properties: field: enum: - displayName.keyword - username.keyword - location.keyword - followers - following - posts - createdAt - lastActiveAt - lastContactedAt - valuation description: The field to sort results by. examples: - followers direction: enum: - asc - desc description: Sort direction. examples: - desc required: - field - direction description: >- Sort order for results. Defaults to followers descending. Available fields: displayName.keyword, username.keyword, location.keyword, followers, following, posts, createdAt, lastActiveAt, lastContactedAt, valuation. style: deepObject explode: true allowEmptyValue: true allowReserved: true responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/LeadWithProspect' nextCursor: anyOf: - type: string - type: 'null' description: >- Cursor to fetch the next page. Null if there are no more results. required: - data - nextCursor components: schemas: LeadWithProspect: type: object properties: 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 description: Full prospect profile data. 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. threads: anyOf: - type: array items: type: object properties: id: type: string pattern: ^[0-9a-z]+$ accountLinkId: type: string pattern: ^[0-9a-z]+$ lastMessageTimestamp: anyOf: - type: string format: date-time - type: 'null' createdAt: type: string format: date-time required: - id - accountLinkId - lastMessageTimestamp - createdAt - type: 'null' description: Threads across all accounts linked to this prospect. required: - tags - statusId - valuation - notes description: CRM context for this prospect (tags, status, valuation, notes). data: anyOf: - type: object propertyNames: type: string additionalProperties: type: string - type: 'null' description: >- Custom column values for this lead. Keys are column IDs (not column names). Use the columns API to look up column IDs. examples: - custom_q5cktl47a6pqa74eu06fz89v: Acme Corp custom_m8r2xj93hd5bk0atcw7oe4fp: CEO stage: anyOf: - enum: - pending - ready - ongoing - replied - unresponsive - failed - canceled - type: 'null' description: >- Campaign stage for this lead. Only present when querying leads on a campaign list. Null for regular lists. accountLinkId: anyOf: - type: string - type: 'null' description: >- The account link ID assigned to contact this lead. Only present for campaign lists. Null for regular lists or if not yet assigned. threadId: anyOf: - type: string - type: 'null' description: >- The thread ID of the conversation with this lead. Only present for campaign lists. Null for regular lists or if no conversation exists yet. required: - prospect - context - data - stage - accountLinkId - threadId description: A lead with full prospect profile, CRM context, and custom column data. ````