> ## 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. # List leads > List campaign leads with cursor-based pagination, optional filters, search, and sorting. Returns full prospect data including CRM context, custom column values, and campaign stage. ## OpenAPI ````yaml get /campaigns/{campaignId}/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: /campaigns/{campaignId}/leads: get: tags: - Campaigns summary: List leads description: >- List campaign leads with cursor-based pagination, optional filters, search, and sorting. Returns full prospect data including CRM context, custom column values, and campaign stage. operationId: campaigns.campaign.leads.list parameters: - name: campaignId in: path required: true schema: type: string pattern: ^[0-9a-z]+$ description: The ID of the campaign. - 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: stage in: query required: false schema: enum: - pending - ready - ongoing - replied - unresponsive - failed - canceled description: Filter leads by their campaign stage. style: form explode: false 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. 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 for advanced filtering. 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. 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. ````