LeadIQ

LeadIQ Lists API

The lists API from LeadIQ — 5 operation(s) for lists.

GitHub OpenAPI

Operations 7

POST /v1/lists
GET /v1/lists
GET /v1/lists/{listId}
GET /v1/lists/{listId}/prospects
POST /v1/lists/{listId}/prospects Create a prospect in a list
POST /v1/lists/{listId}/prospects/batch Create multiple prospects in a list (batch)
POST /v1/lists/{listId}/prospects/{prospectId} Attach an existing prospect to a list

Documentation

📖
Documentation
https://leadiqhelp.zendesk.com/hc/en-us/articles/29375289152795-LeadIQ-Public-API-Guide
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/leadiq/refs/heads/main/authentication/leadiq-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/leadiq/refs/heads/main/openapi/leadiq-lists-api-openapi.yml

Other Resources

🔗
Examples
https://github.com/leadiq/api-samples
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/leadiq/refs/heads/main/errors/leadiq-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/leadiq/refs/heads/main/data-model/leadiq-data-model.yml
🔗
Contact
mailto:api@leadiq.com

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/leadiq-lists-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

leadiq-lists-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Prospector Lists API
  version: 1.0.0
  description: External REST API for LeadIQ prospector lists and prospects.
servers:
- url: https://prospector.leadiq.com
  description: LeadIQ Prospector REST API production host
security:
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: lists
paths:
  /v1/lists:
    post:
      tags:
      - lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInput'
      responses:
        '201':
          description: List created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '400':
          description: Invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A list with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - lists
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          example: 25
        required: false
        name: limit
        in: query
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: false
        name: cursor
        in: query
      - schema:
          allOf:
          - $ref: '#/components/schemas/ListRole'
          - description: Filter to lists where the caller has this role. Omitted = both owner and collaborator.
        required: false
        description: Filter to lists where the caller has this role. Omitted = both owner and collaborator.
        name: role
        in: query
      responses:
        '200':
          description: Lists accessible to the caller (as owner or collaborator).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLists'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lists/{listId}:
    get:
      tags:
      - lists
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: listId
        in: path
      responses:
        '200':
          description: List detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found or not accessible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lists/{listId}/prospects:
    get:
      tags:
      - lists
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: listId
        in: path
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          example: 25
        required: false
        name: limit
        in: query
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: false
        name: cursor
        in: query
      responses:
        '200':
          description: Prospects in list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProspects'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found or not accessible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - lists
      summary: Create a prospect in a list
      description: 'Creates a new prospect and attaches it to the given list.


        **This endpoint is not idempotent.** Each call creates a distinct prospect, even when the body is identical to a previous request — there is no deduplication by email, LinkedIn URL, or any other field. Clients that retry on network errors or 5xx responses must guard against double-create themselves (e.g. by tracking a stable client-side request id and only retrying when the previous attempt did not return a 2xx).'
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: listId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProspectInput'
      responses:
        '201':
          description: Prospect created and attached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found or not accessible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Temporary upstream error — retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lists/{listId}/prospects/batch:
    post:
      tags:
      - lists
      summary: Create multiple prospects in a list (batch)
      description: 'Creates up to 100 prospects in one call and attaches them all to the given list.


        **Partial-success semantics:** the response always returns 200 if the request is well-formed and the caller owns the list. The body contains `succeeded[]` and `failed[]`. `failed[i].index` refers to the position of the failing item in the request body array. Successes appear in `succeeded[]` in input order; failures are sorted by `index`.


        **This endpoint is not idempotent.** Retrying after a network error or timeout may create duplicates. Clients that retry must guard against double-create at their own layer.'
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: listId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProspectInput'
      responses:
        '200':
          description: Per-item result; check failed[] for partial failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSaveResult'
        '400':
          description: Invalid body (e.g. > 100 items, invalid email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found or not accessible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Body too large (server-side body-size cap)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lists/{listId}/prospects/{prospectId}:
    post:
      tags:
      - lists
      summary: Attach an existing prospect to a list
      description: Attaches an existing prospect to the given list. **Idempotent** — calling twice with the same `(listId, prospectId)` pair both return 200 and the resulting `listIds` array contains the list id once, not twice. The caller must be able to access the destination list (owner or collaborator). The prospect must either already be a member of one of the caller's accessible lists, or have been created standalone by the same caller via `POST /v1/prospects`. The 200 body is the post-update prospect with the new `listIds`.
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: listId
        in: path
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: prospectId
        in: path
      responses:
        '200':
          description: Prospect attached (or already attached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '400':
          description: Malformed `listId` or `prospectId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List or prospect not found or not accessible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PaginatedLists:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/List'
        nextCursor:
          type: string
          nullable: true
          pattern: ^[0-9a-fA-F]{24}$
      required:
      - items
      - nextCursor
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          nullable: true
      required:
      - code
      - message
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        domain:
          type: string
        industry:
          type: string
        employees:
          type: integer
        location:
          $ref: '#/components/schemas/CompanyLocation'
        phone:
          type: string
    PaginatedProspects:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Prospect'
        nextCursor:
          type: string
          nullable: true
          pattern: ^[0-9a-fA-F]{24}$
      required:
      - items
      - nextCursor
    CompanyLocation:
      type: object
      properties:
        streetLine1:
          type: string
        streetLine2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        formatted:
          type: string
    Prospect:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        personId:
          type: string
        linkedinId:
          type: string
        linkedinUrl:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        name:
          type: string
        picture:
          type: string
        title:
          type: string
        seniority:
          type: string
        function:
          type: string
        workEmail:
          type: string
        emailStatus:
          type: string
        personalEmails:
          type: array
          items:
            type: string
        mobilePhones:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              status:
                type: string
                enum:
                - Verified
            required:
            - value
        location:
          $ref: '#/components/schemas/Location'
        company:
          $ref: '#/components/schemas/Company'
        listIds:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
        notes:
          type: string
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
      required:
      - id
      - listIds
      - createdAt
      - updatedAt
    List:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        name:
          type: string
        role:
          $ref: '#/components/schemas/ListRole'
        description:
          type: string
        status:
          type: string
        visibility:
          type: string
        startDate:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
        endDate:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-15T12:34:56.789Z'
      required:
      - id
      - name
      - role
      - createdAt
      - updatedAt
    BulkSaveFailure:
      type: object
      properties:
        index:
          type: integer
          minimum: 0
        reason:
          type: string
      required:
      - index
      - reason
    ListInput:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
      required:
      - name
      additionalProperties: false
    BulkSaveResult:
      type: object
      properties:
        succeeded:
          type: array
          items:
            $ref: '#/components/schemas/Prospect'
        failed:
          type: array
          items:
            $ref: '#/components/schemas/BulkSaveFailure'
      required:
      - succeeded
      - failed
    BulkProspectInput:
      type: array
      items:
        $ref: '#/components/schemas/ProspectInput'
      minItems: 1
      maxItems: 100
    ListRole:
      type: string
      enum:
      - owner
      - collaborator
      description: Caller's relationship to the list. `owner` means the caller created it; `collaborator` means another member granted them edit access.
    Location:
      type: object
      properties:
        streetLine1:
          type: string
        streetLine2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        formatted:
          type: string
    ProspectInput:
      type: object
      properties:
        firstName:
          type: string
          minLength: 1
        lastName:
          type: string
          minLength: 1
        workEmail:
          type: string
          format: email
        phone:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        seniority:
          type: string
          enum:
          - VP
          - Manager
          - Director
          - Executive
          - SeniorIndividualContributor
          - Other
        function:
          type: string
          minLength: 1
        company:
          type: string
          minLength: 1
        companyDomain:
          type: string
          minLength: 1
        companyIndustry:
          type: string
          minLength: 1
        companyId:
          type: string
          minLength: 1
          description: DataIQ company id. Provide it to link the lead to the company and enrich company data
        linkedinUrl:
          type: string
          format: uri
        emailStatus:
          type: string
          enum:
          - Unverified
          - Verified
          - VerifiedLikely
        location:
          $ref: '#/components/schemas/Location'
        notes:
          type: string
          maxLength: 5000
        personId:
          type: string
          minLength: 1
          description: DataIQ ID. Provide it for better matching and deduplication
      required:
      - firstName
      - lastName
      additionalProperties: false
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Send your LeadIQ API key as the `X-API-Key` header value — no prefix, no encoding.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 access token (JWT) issued for an audience accepted by this service.