LeadIQ Prospector REST API

openapi: 3.1.0
info:
  title: Prospector 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: []
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'
  /v1/prospects:
    get:
      tags:
      - prospects
      summary: List or search prospects
      description: Find prospects across all of the caller's leads, regardless of list membership. Pass **either** `email`
        alone, **or** `firstName` + `lastName` together, **or** no criteria to list every prospect the caller owns. Half-name
        searches and combined email+name are rejected with 400.
      parameters:
      - schema:
          type: string
          format: email
        required: false
        name: email
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        name: firstName
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        name: lastName
        in: query
      - 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: Matching prospects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProspects'
        '400':
          description: Invalid query (missing or mixed criteria)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - prospects
      summary: Create a prospect (no list)
      description: 'Creates a new prospect with no list membership. Use `POST /v1/lists/{listId}/prospects` instead to create-and-attach
        in a single call.


        **This endpoint is not idempotent.** See the same note on `POST /v1/lists/{listId}/prospects`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProspectInput'
      responses:
        '201':
          description: Prospect created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '400':
          description: Invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          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'
        '502':
          description: Temporary upstream error — retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/verify-email:
    get:
      tags:
      - prospects
      summary: Verify a standalone email address
      description: Verify any email without creating or modifying a lead. Useful as a pre-flight check before creating a prospect.
        The verdict is computed by EVS (Email Verification Service) and folded into our four-value status enum.
      parameters:
      - schema:
          type: string
          format: email
          example: someone@example.com
        required: true
        name: email
        in: query
      responses:
        '200':
          description: Verification verdict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyStandaloneEmailResponse'
        '400':
          description: Missing or malformed `email`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: EVS unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/prospects/{prospectId}:
    get:
      tags:
      - prospects
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: prospectId
        in: path
      responses:
        '200':
          description: Prospect detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '400':
          description: Malformed `prospectId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found or not visible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/prospects/{prospectId}/verify-email:
    post:
      tags:
      - prospects
      summary: Verify the email on an existing prospect
      description: 'Verifies the email currently stored on the lead and persists the new status. The lead''s `workEmail` field
        is **never** modified — this is a verify-what''s-there operation, not a discover-and-replace one. Returns 409 with
        `code: "no_email_to_verify"` if the lead has no email (a state precondition, not a body-validation failure).'
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: prospectId
        in: path
      responses:
        '200':
          description: Verification verdict + post-update prospect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailResponse'
        '400':
          description: Malformed `prospectId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found or not visible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Lead has no email to verify (state precondition)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: EVS unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/prospects/{prospectId}/export/salesforce:
    post:
      tags:
      - prospects
      summary: Export a prospect into the caller's Salesforce
      description: 'Creates (or enriches) a Lead or Contact in the Salesforce org connected to the calling user, using the
        same export pipeline as the LeadIQ web app. Acts as the caller''s connected Salesforce user, so their Salesforce permissions,
        validation rules and duplicate rules all still apply.


        **Writes to an external system of record and cannot be undone by this API.** There is no delete path, and this endpoint
        is **not idempotent** — retrying may create a second record.


        Whether the prospect is saved as a Lead or a Contact is decided by the member''s `Save to` setting and the org''s
        governance; it is deliberately not selectable here.


        May consume Universal Credits when the prospect carries a DataIQ company id that the org has not already unlocked
        — the export unlocks company data to populate the Salesforce Account.


        `200` reports a terminal outcome, **including `duplicates_found`, where nothing was written.** `202` means the export
        was handed off but its outcome is unknown; do not retry on a `202`.'
      parameters:
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
        required: true
        name: prospectId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesforceExportRequest'
      responses:
        '200':
          description: Terminal outcome (created, updated, or duplicates found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesforceExportResult'
        '202':
          description: Submitted; terminal outcome unknown. Do not retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesforceExportAccepted'
        '400':
          description: Malformed `prospectId` or body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`salesforce_export_disabled` — a LeadIQ admin has disabled Salesforce export for this org; or `salesforce_export_not_enabled`
            — the feature is still rolling out and is not enabled for the caller''s team yet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found or not visible to caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'State precondition: `salesforce_not_connected`, `salesforce_save_as_unsupported`, `salesforce_account_required`,
            `quality_skipped`, `export_rejected`, or `salesforce_rejected_record`'
          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'
        '502':
          description: Temporary upstream error — safe to retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/whoami:
    get:
      tags:
      - account
      summary: Identify the caller
      description: 'Returns the account behind the presented credentials: the user identity this API scopes ownership by,
        plus the team name and email domain. Useful for verifying which account an API key or token belongs to.'
      responses:
        '200':
          description: The caller's account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoAmI'
        '401':
          description: Unauthorized
          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'
components:
  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.
  schemas:
    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
    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.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          nullable: true
      required:
      - code
      - message
    ListInput:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
      required:
      - name
      additionalProperties: false
    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
    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
    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
    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
    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
    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
    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
    BulkSaveResult:
      type: object
      properties:
        succeeded:
          type: array
          items:
            $ref: '#/components/schemas/Prospect'
        failed:
          type: array
          items:
            $ref: '#/components/schemas/BulkSaveFailure'
      required:
      - succeeded
      - failed
    BulkSaveFailure:
      type: object
      properties:
        index:
          type: integer
          minimum: 0
        reason:
          type: string
      required:
      - index
      - reason
    BulkProspectInput:
      type: array
      items:
        $ref: '#/components/schemas/ProspectInput'
      minItems: 1
      maxItems: 100
    VerifyStandaloneEmailResponse:
      type: object
      prope

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leadiq/refs/heads/main/openapi/leadiq-prospector-api-openapi.yml