ProspectAPIs Research API

openapi: 3.2.0
info:
  title: ProspectAPIs Research API
  summary: Funding signals and cited prospect research over one REST API.
  description: 'The REST contract for ProspectAPIs: funding rounds you can filter and page, cited prospect research briefs, and funding watchlists that push new matches to a webhook. Built for sales teams and the AI agents that work for them.


    Authentication is a bearer API key (`Authorization: Bearer pa_live_`), created in the dashboard. `GET /pricing`, `GET /health` and `GET /v1/version` need no key.


    Every account starts with a one-time free balance (`signup_credit_usd` in `GET /pricing`), and every paid call draws from it at its own price: `GET /v1/funding` per returned record (a no-match is free), `POST /v1/email/verify` per valid or invalid result, `POST /v1/research` per completed brief. Paid responses carry `X-Credits-Remaining`. The live price list is `GET /pricing`; a key''s balance is `GET /v1/account`. This document describes shapes, not prices.'
  version: 0.1.0
  contact:
    name: ProspectAPIs
    url: https://prospectapis.com
    email: emma@prospectapis.com
  license:
    name: Proprietary
    url: https://prospectapis.com/terms
  termsOfService: https://prospectapis.com/terms
servers:
- url: https://api.prospectapis.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Research
  description: Start and poll cited prospect research briefs.
paths:
  /v1/research:
    post:
      tags:
      - Research
      summary: Start a research brief
      description: 'Start a cited research brief on one prospect. Accepts exactly one identifier (`domain`, `website_url`, `company_name`, `company_linkedin_url`, a work `email` or `linkedin_url`), or `person_name` with `company_name`. Returns `202` with a `research_id` at once; poll `GET /v1/research/{id}` until `status` is `completed` or `failed`. Charged at the research price only when the brief completes, and refunded if it fails. Answers `503` while research is not priced. Price: $0.15 per completed brief, charged only when it completes; the live value is research.price_per_research_usd in GET /pricing.'
      operationId: submitResearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRequest'
            example:
              domain: acme.com
              purpose: pre_call
              context: We sell route planning software for 3PLs
      responses:
        '202':
          description: The brief was accepted and is running.
          headers:
            X-Credits-Remaining:
              $ref: '#/components/headers/X-Credits-Remaining'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchAccepted'
              example:
                research_id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                status: status
                estimated_seconds: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ResearchNotPriced'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      x-agentic-access:
        action-class: acting
        consequence: spend
        subject: required
        audience: null
        token:
          max-ttl: 900
        escalation:
          human-in-the-loop: conditional
          triggers:
          - abnormal
          - high-value
        audit: required
        idempotency-key: Idempotency-Key header, replayed for 24 hours
  /v1/research/{id}:
    get:
      tags:
      - Research
      summary: Poll a research brief
      description: One research job, for its owner only (another account's id reads as not found). Free. Poll until `status` is `completed` (the brief is in `result`) or `failed` (the reason is in `error`, and the charge was refunded).
      operationId: getResearch
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The research job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchJob'
              example:
                research_id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                status: status
                input: {}
                result: {}
                error: {}
                created_at: '2026-11-01T12:00:00Z'
                completed_at: '2026-11-01T12:00:00Z'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      description: A UUID.
      schema:
        type: string
        format: uuid
      example: 3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional, 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours gets the first answer back with Idempotent-Replayed: true and is never charged again. The same key with a different body is 422; a retry while the first call is still running is 409.'
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: order-42
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Out of credits. The body carries `top_up_url`; nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResearchNotPriced:
      description: Research is not priced yet; no hold was taken.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; retry after the window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid (e.g. a bad filter or input); nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such record for this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RateLimit-Limit:
      description: Requests this API key may make per minute.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    X-Credits-Remaining:
      description: USD credits left after this call settles.
      schema:
        type: string
  schemas:
    ResearchAccepted:
      type: object
      required:
      - research_id
      - status
      - estimated_seconds
      properties:
        research_id:
          type: string
          format: uuid
        status:
          type: string
          description: The job status at acceptance (queued).
        estimated_seconds:
          type: integer
          description: Roughly how long the brief takes.
    ResearchRequest:
      type: object
      example:
        domain: acme.com
        purpose: pre_call
        context: We sell route planning software for 3PLs
      description: Exactly one prospect identifier, or `person_name` with `company_name`. Unknown fields are refused. An `email` must be a work address (a free-mail domain is refused); URLs must be http(s) on a public host.
      properties:
        domain:
          type: string
          description: A bare company domain such as acme.com.
          example: acme.com
        website_url:
          type: string
          format: uri
        company_name:
          type: string
          maxLength: 200
        company_linkedin_url:
          type: string
          format: uri
          description: A linkedin.com/company/... URL.
        email:
          type: string
          format: email
          description: A work email such as jane@acme.com.
        linkedin_url:
          type: string
          format: uri
          description: A linkedin.com/in/... URL.
        person_name:
          type: string
          maxLength: 200
          description: Only together with company_name.
        context:
          type: string
          maxLength: 1000
          description: Your own product or angle, to tailor the Fit section.
        purpose:
          type: string
          enum:
          - account_research
          - pre_call
          - outreach
          default: account_research
      additionalProperties: false
    ResearchJob:
      type: object
      required:
      - research_id
      - status
      - input
      - result
      - error
      - created_at
      - completed_at
      properties:
        research_id:
          type: string
          format: uuid
        status:
          type: string
          description: queued while it runs, then completed or failed.
        input:
          type: object
          description: The normalised input, echoed back.
          additionalProperties: true
        result:
          type:
          - object
          - 'null'
          description: The cited brief when status is completed, else null.
          additionalProperties: true
        error:
          type:
          - object
          - string
          - 'null'
          description: Why it failed when status is failed, else null.
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
    Error:
      type: object
      required:
      - error
      description: Every error answers with this shape. `error` is a human-readable message; `code` is a stable machine code when present.
      properties:
        error:
          type: string
        code:
          type: string
          description: A stable error code, e.g. INVALID_FILTER, INVALID_INPUT, INVALID_ID, NOT_FOUND, INSUFFICIENT_CREDITS, WATCHLIST_LIMIT, RATE_LIMITED.
        message:
          type: string
          description: Extra guidance on some errors (401, 402).
        field:
          type: string
          description: The offending field, on some 400s.
        top_up_url:
          type: string
          format: uri
          description: Where to add credits, on a 402.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a bearer token: `Authorization: Bearer pa_live_<48 hex>`. Create and manage keys in the dashboard at https://prospectapis.com.'
externalDocs:
  description: API reference and quickstart
  url: https://prospectapis.com/docs