> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rapportapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Research

> Start a new research lookup for a prospect. Requires at least one identifier: email, linkedin_url, or full_name + company. Returns a task_id for polling. Costs 1 credit.



## OpenAPI

````yaml POST /research
openapi: 3.1.0
info:
  title: RapportAPI
  description: >-
    Sales intelligence API. Submit a person's identifier and receive deep
    intelligence reports with icebreakers, communication style guides, and
    background research.
  version: 1.0.0
  contact:
    name: RapportAPI Support
    email: support@rapportapi.com
    url: https://rapportapi.com
servers:
  - url: https://api.rapportapi.com
    description: Production
security:
  - bearerAuth: []
paths:
  /research:
    post:
      summary: Submit research request
      description: >-
        Start a new research lookup for a prospect. Requires at least one
        identifier: email, linkedin_url, or full_name + company. Returns a
        task_id for polling. Costs 1 credit.
      operationId: submitResearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRequest'
            example:
              contact_data:
                email: jane@example.com
              callback_url: https://yourapp.com/webhooks/rapport
              callback_secret: your_webhook_secret
      responses:
        '202':
          description: Research request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchSubmitted'
              example:
                task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                prospect_id: null
                status: pending
        '400':
          description: Invalid request — missing required identifiers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: >-
                  Invalid request body: at least one identifier required (email,
                  linkedin_url, or full_name + company)
                status_code: 400
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Insufficient credits. Please purchase more at rapportapi.com.
                status_code: 402
components:
  schemas:
    ResearchRequest:
      type: object
      required:
        - contact_data
      properties:
        contact_data:
          $ref: '#/components/schemas/ContactData'
        prospect_id:
          type: string
          description: >-
            Your internal ID for this prospect (echoed back in responses and
            webhooks)
        callback_url:
          type: string
          format: uri
          description: URL to receive a webhook POST when research completes
        callback_secret:
          type: string
          description: Bearer token sent in the Authorization header of webhook callbacks
        is_test:
          type: boolean
          default: false
          description: >-
            If true, returns a dummy completed response immediately without
            using credits. Useful for testing your integration.
    ResearchSubmitted:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
          description: Unique task ID for polling
        prospect_id:
          type: string
          nullable: true
          description: Your prospect_id if provided
        status:
          type: string
          enum:
            - pending
          description: Initial status is always 'pending'
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message
        status_code:
          type: integer
          description: HTTP status code
    ContactData:
      type: object
      description: >-
        Contact identifiers. At least one of: email, linkedin_url, or full_name
        + company.
      properties:
        email:
          type: string
          format: email
          description: Email address (sufficient as sole identifier)
        linkedin_url:
          type: string
          format: uri
          description: >-
            LinkedIn profile URL (sufficient as sole identifier, unlocks post
            analysis)
        full_name:
          type: string
          description: Full name (requires company)
        company:
          type: string
          description: Company name (requires full_name)
        first_name:
          type: string
          description: First name (optional, improves matching)
        last_name:
          type: string
          description: Last name (optional, improves matching)
        phone:
          type: string
          description: Phone number (optional, improves enrichment)
        title:
          type: string
          description: Job title (optional, improves enrichment)
        location:
          type: string
          description: Location (optional, improves enrichment)
        twitter_url:
          type: string
          format: uri
          description: Twitter/X profile URL (optional, unlocks tweet analysis)
        facebook_url:
          type: string
          format: uri
          description: Facebook profile URL (optional)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key with rapi_live_ prefix

````