openapi: 3.2.0
info:
  title: Prospector Prospects 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: prospects
paths:
  /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'
components:
  schemas:
    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
    SalesforceExportAccepted:
      type: object
      properties:
        status:
          type: string
          enum:
          - submitted
        requestId:
          type: string
        savedAs:
          type: string
        message:
          type: string
      required:
      - status
      - message
    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
    VerifyEmailResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - Verified
          - VerifiedLikely
          - Unverified
          - Invalid
        prospect:
          $ref: '#/components/schemas/Prospect'
      required:
      - status
      - prospect
    VerifyStandaloneEmailResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - Verified
          - VerifiedLikely
          - Unverified
          - Invalid
      required:
      - status
    SalesforceExportResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - created
          - updated
          - duplicates_found
          description: '`created` — a new Salesforce record exists. `updated` — an existing record was enriched; **not currently returned** — this endpoint always attempts an insert and cannot target an existing Salesforce record, so the value is reserved for when that becomes possible. `duplicates_found` — **nothing was written**; see `duplicates`.'
        entityId:
          type: string
          description: Salesforce id of the created/updated record. Absent on `duplicates_found`, and possible to be absent on `updated`.
        entityType:
          type: string
        savedAs:
          type: string
          description: Which Salesforce object the export targeted, decided by the member's `Save to` setting and the org's governance — not by this API.
        requestId:
          type: string
          description: Correlation id for the export, for support lookups.
        duplicates:
          type: array
          items:
            $ref: '#/components/schemas/SalesforceDuplicate'
          description: Present on `duplicates_found`.
      required:
      - status
    SalesforceExportRequest:
      type: object
      properties:
        force:
          type: boolean
          default: false
          description: 'Create the record even though Salesforce reported possible duplicates. Only send `true` after a previous call returned `status: "duplicates_found"` and a human confirmed none of the candidates is the same person. Forcing blindly is the main way duplicate Leads get into a customer CRM.'
          example: false
      additionalProperties: false
    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
    SalesforceDuplicate:
      type: object
      properties:
        id:
          type: string
          description: Salesforce record id.
        entityType:
          type: string
          description: Salesforce object of the candidate, e.g. `Lead`.
        name:
          type: string
        email:
          type: string
        company:
          type: string
      required:
      - id
      - entityType
    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.