---
title: "POST /org-storage/leads/by-list/{listId}"
method: POST
path: "/org-storage/leads/by-list/{listId}"
tags: ["org-storage"]
---

# POST /org-storage/leads/by-list/{listId}

`POST /org-storage/leads/by-list/{listId}`

## Request

- Base URL: `https://api.phantombuster.com/api/v2`
- URL: `https://api.phantombuster.com/api/v2/org-storage/leads/by-list/{listId}`
- Auth: API key in header `X-Phantombuster-Key`
- TypeScript: <https://skmtc.dev/phantombuster/apis/phantombuster-api-v2/docs/org-storage/leads/by-list/:listId/post.ts> (a function with typed inputs; its response is checked against the schema)

Fetch leads by their list id.

## Path parameters

- `listId` string, required

## Headers

- `X-Phantombuster-Org` string

## Request body

- object
  - `paginationOptions` object: Options for pagination
    - `paginationOrder` 'ASC' | 'DESC': Sort your leads by creation date
    - `paginationSize` number: Number of leads per page
    - `paginationOffset` number: Offset to start looking for leads at
    - `paginationProperty` string: Property to sort the leads
    - `includeTotalCount` boolean: Should the response return total items count
  - `withLeadObjectsOfTypes` string[]: Array of lead object types
  - `withCompanies` boolean: Option for retrieving the company associated to the lead

## Response `200`

OK.

- union
  - object
    - `leads` object[], required
      - `isCreation` boolean: Indicates if the lead is created or inserted
      - `id` string, required
      - `linkedinProfileSlug` string, required
      - `linkedinCompanySlug` string
      - `twitterProfileHandle` string
      - `linkedinPreviousCompanySlug` string
      - `linkedinSchoolCompanySlug` string
      - `linkedinPreviousSchoolCompanySlug` string
      - `salesNavigatorProfileId` string
      - `salesNavigatorCompanyId` string
      - `firstName` string: lead firstName
      - `lastName` string: lead lastName
      - `location` string: lead location
      - `civility` string: lead civility
      - `linkedinOpenProfile` boolean: lead linkedin profile is open
      - `linkedinIsHiringBadge` boolean: lead linkedin is hiring badge
      - `linkedinIsOpenToWorkBadge` boolean: lead linkedin is open to work badge
      - `professionalEmails` string[]: lead professional emails
      - `personalEmails` string[]: lead personal emails
      - `phoneNumbers` string[]: lead phone numbers
      - `websites` string[]: lead websites
      - `companyName` string: lead company
      - `companyWebsite` string: lead company website
      - `linkedinCompanyId` string: linkedin company id
      - `linkedinProfileId` string: lead linkedin profile id
      - `linkedinProfileUrn` string: lead linkedin profile urn
      - `linkedinProfileImageUrn` string: lead linkedin profile picture image urn
      - `linkedinProfileImageUrl` string: lead linkedin profile picture image url
      - `linkedinHeadline` string: lead linkedin profile headline
      - `linkedinJobTitle` string: lead linkedin job title
      - `linkedinJobDateRange` string: lead linkedin job date range
      - `linkedinJobLocation` string: lead linkedin job location
      - `companyIndustry` string: industry of the lead's company
      - `linkedinFollowersCount` number: lead linkedin followers count
      - `linkedinDescription` string: lead linkedin description
      - `linkedinJobDescription` string: lead linkedin job description
      - `linkedinPreviousJobDescription` string: lead linkedin previous job description
      - `linkedinSkillsLabel` string: lead linkedin skills label
      - `previousCompanyName` string: lead previous company name
      - `linkedinPreviousJobTitle` string: lead previous job title
      - `linkedinPreviousJobDateRange` string: lead previous job date range
      - `linkedinPreviousJobLocation` string: lead previous job location
      - `linkedinSchoolName` string: lead linkedin school name
      - `linkedinPreviousSchoolName` string: lead linkedin previous school name
      - `linkedinSchoolDegree` string: lead linkedin school degree
      - `linkedinPreviousSchoolDegree` string: lead linkedin previous school degree
      - `linkedinSchoolDateRange` string: lead linkedin school date range
      - `linkedinPreviousSchoolDateRange` string: lead linkedin previous school date range
      - `linkedinSchoolDescription` string: lead linkedin school description
      - `linkedinPreviousSchoolDescription` string: lead linkedin previous school description
      - `linkedinAccountRelativeProperties` object[]: Collection of Lead LinkedIn properties grouped by scraping LinkedIn user
        - `sourceUserId` string, required: Source LinkedIn profile id (user who scraped)
        - `connectionDegree` integer: Lead LinkedIn connection degree
      - `crmAccountRelativeProperties` object[]: Collection of CRM related properties grouped by CRM name (contains only one item per CRM)
        - `crmContactId` string, required
        - `crmAccountId` string, required
        - `crmName` 'hubspot' | 'pipedrive' | 'salesforce', required
      - `audienceOfLeads` string[]: list of lead ids this lead is an audience of
      - `editionsHistory` union[], required
        - union
          - object
            - `type` 'agent', required
            - `timestamp` number, required
            - `mainAgentId` string, required
            - `workerAgentId` string
            - `resultFile` string
            - `errorMessage` string
            - `identityProfileId` string: Source profile id (user who scraped)
            - `identityType` 'linkedin'
          - object
            - `type` 'manual', required
            - `timestamp` number, required
            - `userId` string
            - `editedProperties` string[], required
          - object
            - `type` 'browser_extension', required
            - `timestamp` number, required
            - `extensionType` 'chrome' | 'firefox' | 'edge', required
      - `metadata` object: metadata for the lead
      - `aiGeneratedProperties` object: AI generated properties
      - `company` object
        - `id` string, required
        - `companyId` string, required
        - `companySlug` string, required
        - `properties` object, required
        - `createdAt` number, required
        - `updatedAt` number, required
    - `totalCount` number, required
  - object[]
    - `isCreation` boolean: Indicates if the lead is created or inserted
    - `id` string, required
    - `linkedinProfileSlug` string, required
    - `linkedinCompanySlug` string
    - `twitterProfileHandle` string
    - `linkedinPreviousCompanySlug` string
    - `linkedinSchoolCompanySlug` string
    - `linkedinPreviousSchoolCompanySlug` string
    - `salesNavigatorProfileId` string
    - `salesNavigatorCompanyId` string
    - `firstName` string: lead firstName
    - `lastName` string: lead lastName
    - `location` string: lead location
    - `civility` string: lead civility
    - `linkedinOpenProfile` boolean: lead linkedin profile is open
    - `linkedinIsHiringBadge` boolean: lead linkedin is hiring badge
    - `linkedinIsOpenToWorkBadge` boolean: lead linkedin is open to work badge
    - `professionalEmails` string[]: lead professional emails
    - `personalEmails` string[]: lead personal emails
    - `phoneNumbers` string[]: lead phone numbers
    - `websites` string[]: lead websites
    - `companyName` string: lead company
    - `companyWebsite` string: lead company website
    - `linkedinCompanyId` string: linkedin company id
    - `linkedinProfileId` string: lead linkedin profile id
    - `linkedinProfileUrn` string: lead linkedin profile urn
    - `linkedinProfileImageUrn` string: lead linkedin profile picture image urn
    - `linkedinProfileImageUrl` string: lead linkedin profile picture image url
    - `linkedinHeadline` string: lead linkedin profile headline
    - `linkedinJobTitle` string: lead linkedin job title
    - `linkedinJobDateRange` string: lead linkedin job date range
    - `linkedinJobLocation` string: lead linkedin job location
    - `companyIndustry` string: industry of the lead's company
    - `linkedinFollowersCount` number: lead linkedin followers count
    - `linkedinDescription` string: lead linkedin description
    - `linkedinJobDescription` string: lead linkedin job description
    - `linkedinPreviousJobDescription` string: lead linkedin previous job description
    - `linkedinSkillsLabel` string: lead linkedin skills label
    - `previousCompanyName` string: lead previous company name
    - `linkedinPreviousJobTitle` string: lead previous job title
    - `linkedinPreviousJobDateRange` string: lead previous job date range
    - `linkedinPreviousJobLocation` string: lead previous job location
    - `linkedinSchoolName` string: lead linkedin school name
    - `linkedinPreviousSchoolName` string: lead linkedin previous school name
    - `linkedinSchoolDegree` string: lead linkedin school degree
    - `linkedinPreviousSchoolDegree` string: lead linkedin previous school degree
    - `linkedinSchoolDateRange` string: lead linkedin school date range
    - `linkedinPreviousSchoolDateRange` string: lead linkedin previous school date range
    - `linkedinSchoolDescription` string: lead linkedin school description
    - `linkedinPreviousSchoolDescription` string: lead linkedin previous school description
    - `linkedinAccountRelativeProperties` object[]: Collection of Lead LinkedIn properties grouped by scraping LinkedIn user
      - `sourceUserId` string, required: Source LinkedIn profile id (user who scraped)
      - `connectionDegree` integer: Lead LinkedIn connection degree
    - `crmAccountRelativeProperties` object[]: Collection of CRM related properties grouped by CRM name (contains only one item per CRM)
      - `crmContactId` string, required
      - `crmAccountId` string, required
      - `crmName` 'hubspot' | 'pipedrive' | 'salesforce', required
    - `audienceOfLeads` string[]: list of lead ids this lead is an audience of
    - `editionsHistory` union[], required
      - union
        - object
          - `type` 'agent', required
          - `timestamp` number, required
          - `mainAgentId` string, required
          - `workerAgentId` string
          - `resultFile` string
          - `errorMessage` string
          - `identityProfileId` string: Source profile id (user who scraped)
          - `identityType` 'linkedin'
        - object
          - `type` 'manual', required
          - `timestamp` number, required
          - `userId` string
          - `editedProperties` string[], required
        - object
          - `type` 'browser_extension', required
          - `timestamp` number, required
          - `extensionType` 'chrome' | 'firefox' | 'edge', required
    - `metadata` object: metadata for the lead
    - `aiGeneratedProperties` object: AI generated properties
    - `company` object
      - `id` string, required
      - `companyId` string, required
      - `companySlug` string, required
      - `properties` object, required
      - `createdAt` number, required
      - `updatedAt` number, required

---

[API](https://skmtc.dev/phantombuster/apis/phantombuster-api-v2.md) - [All operations](https://skmtc.dev/phantombuster/apis/phantombuster-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/phantombuster/apis/phantombuster-api-v2/revisions/acf0049d7c7f?raw)