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

# Get a deal

> One deal with its full terms, lifecycle events and source documents.



## OpenAPI

````yaml /openapi.json get /v1/deals/{deal_id}
openapi: 3.1.0
info:
  title: Pav Enterprise API
  description: >-
    Read-only API over Pav's biopharma data: programs, drugs, companies, trials,
    deals, patents, FDA records and changes. Send `Authorization: Bearer
    <api_key>`. Lists return `{data, next_cursor, total}`; errors return
    `{error: {code, message, request_id}}`. Parameter rules:
    [Conventions](https://docs.pav.bio/conventions).
  version: 2.0.0
servers:
  - url: https://api.pav.bio
    description: Production
security: []
tags:
  - name: search
    description: Find the id of a company, drug, program, target or indication.
    x-group: Search
  - name: programs
    description: 'Drug programs: one drug in one indication at one company.'
    x-group: Programs
  - name: drugs
    description: >-
      One drug product across every company that develops it, under all its
      names, with its programs.
    x-group: Drugs
  - name: companies
    description: Biopharma companies, their owners and their trials.
    x-group: Companies
  - name: trials
    description: ClinicalTrials.gov trials linked to programs and companies.
    x-group: Trials
  - name: deals
    description: M&A, licensing and collaboration deals with terms and sources.
    x-group: Deals
  - name: patents
    description: US patent families with owners, members and term.
    x-group: Patents
  - name: fda
    description: FDA records, one endpoint per record type.
    x-group: FDA
  - name: changes
    description: Program and trial changes, newest first.
    x-group: Changes
  - name: stats
    description: Dataset counts.
    x-group: Stats
paths:
  /v1/deals/{deal_id}:
    get:
      tags:
        - deals
      summary: Get a deal
      description: One deal with its full terms, lifecycle events and source documents.
      operationId: get_deal
      parameters:
        - name: deal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Deal id.
            examples:
              - ec0bcf74-fdc0-4ffa-ad04-fe25ed8d6210
            title: Deal Id
          description: Deal id.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealDetail'
        '400':
          description: Invalid parameter (`validation_error`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key (`unauthorized`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Unknown id or route (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded (`rate_limited`); honor `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - EnterpriseApiKey: []
components:
  schemas:
    DealDetail:
      properties:
        deal_id:
          type: string
          format: uuid
          title: Deal Id
          description: Stable Pav deal identifier.
          examples:
            - ec0bcf74-fdc0-4ffa-ad04-fe25ed8d6210
        deal_name:
          type: string
          title: Deal Name
          description: Deal headline.
          examples:
            - Merck KGaA acquisition of Bio-Techne Corporation
        deal_type:
          type: string
          enum:
            - acquisition
            - merger
            - asset_purchase
            - licensing
            - collaboration
            - option
            - joint_venture
            - distribution
            - other
          title: Deal Type
          description: Deal classification.
          examples:
            - acquisition
        latest_event_type:
          type: string
          enum:
            - proposed
            - announced
            - completed
            - amended
            - terminated
            - update
          title: Latest Event Type
          description: >-
            Current state: `proposed`, `announced`, `amended`, `completed` or
            `terminated`. Never moves backwards.
          examples:
            - completed
        latest_event_name:
          type: string
          title: Latest Event Name
          description: Headline of the event that set the current state.
        latest_event_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Event At
          description: When the current state took effect (UTC), when stated.
        activity_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Activity Date
          description: >-
            Latest activity: the later of `latest_event_at` and
            `latest_update_at`, else the latest source's publish date. Default
            sort key.
        announced_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Announced At
          description: Announcement date (UTC).
        latest_update_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Update At
          description: Most recent update mention (UTC).
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: Completion date (UTC).
        summary:
          type: string
          title: Summary
          description: One-paragraph deal summary.
        companies:
          items:
            $ref: '#/components/schemas/DealCompany'
          type: array
          title: Companies
          description: Parties linked to Pav companies.
        total_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: >-
            Headline (total) deal value as the announcement states it, updated
            when an acquisition price is amended. Never a per-share price.
        total_potential_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: >-
            `total_value` when stated, else upfront plus milestones in one
            currency.
        upfront:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Upfront consideration.
        development_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Development milestone economics.
        regulatory_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Regulatory milestone economics.
        commercial_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Commercial / sales milestone economics.
        source_document_count:
          type: integer
          title: Source Document Count
          description: Distinct source documents behind the deal.
        event_count:
          type: integer
          title: Event Count
          description: Lifecycle events recorded for the deal.
        assets:
          items:
            $ref: '#/components/schemas/DealAsset'
          type: array
          title: Assets
          description: Drugs the deal covers. Empty when it names no specific drug.
        targets:
          items:
            $ref: '#/components/schemas/DealTarget'
          type: array
          title: Targets
          description: Molecular targets of the deal's drugs, as ontology terms.
        modalities:
          items:
            type: string
          type: array
          title: Modalities
          description: Modalities of the deal's drugs, in Pav's modality vocabulary.
          examples:
            - - antibody
        therapeutic_areas:
          items:
            type: string
          type: array
          title: Therapeutic Areas
          description: >-
            Therapeutic areas of the diseases the deal's drugs are developed
            for, as area slugs (for example `oncology`, `immunology`,
            `endocrine_metabolic`).
          examples:
            - - immunology
              - gastroenterology
        terms:
          $ref: '#/components/schemas/DealTerms'
          description: Economics and rights across all source documents.
        events:
          items:
            $ref: '#/components/schemas/DealEvent'
          type: array
          title: Events
          description: Lifecycle events, oldest first.
        source_documents:
          items:
            $ref: '#/components/schemas/DealSourceDocument'
          type: array
          title: Source Documents
          description: Source documents behind the deal, oldest first.
      type: object
      required:
        - deal_id
        - deal_name
        - deal_type
        - latest_event_type
        - latest_event_name
        - summary
        - source_document_count
        - event_count
        - terms
      title: DealDetail
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      type: object
    DealCompany:
      properties:
        company_id:
          type: integer
          title: Company Id
          description: Durable Pav company identifier.
          examples:
            - 239
        short_name:
          type: string
          title: Short Name
          description: Company slug.
          examples:
            - merck_kgaa
        name:
          type: string
          title: Name
          description: Company display name.
          examples:
            - Merck KGaA
        roles:
          items:
            type: string
          type: array
          title: Roles
          description: >-
            The company's roles: acquirer, target, seller, licensor, licensee,
            collaborator, investor, issuer, other.
          examples:
            - - acquirer
      type: object
      required:
        - company_id
        - short_name
        - name
      title: DealCompany
    DealValue:
      properties:
        raw_text:
          type: string
          title: Raw Text
          description: The term as the source states it.
          examples:
            - total enterprise value of approximately US$11.3 billion
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
          description: >-
            Monetary amount in base currency units. Null for percentages or
            unstated values.
          examples:
            - 11300000000
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
          description: ISO 4217 code for `amount`.
          examples:
            - USD
        percentage:
          anyOf:
            - type: number
            - type: 'null'
          title: Percentage
          description: Percentage value (royalties, equity).
          examples:
            - null
        not_disclosed:
          type: boolean
          title: Not Disclosed
          description: True when the source explicitly withholds this term.
          default: false
        evidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Evidence
          description: Source sentence supporting the value.
      type: object
      required:
        - raw_text
      title: DealValue
    DealAsset:
      properties:
        drug_id:
          type: integer
          title: Drug Id
          description: >-
            Pav drug id: one drug product across every company that develops it
            (`GET /v1/drugs/{drug_id}`).
          examples:
            - 8880
        name:
          type: string
          title: Name
          description: Drug display name.
          examples:
            - tulisokibart
        modality:
          anyOf:
            - type: string
            - type: 'null'
          title: Modality
          description: The drug's modality, normalized to Pav's modality vocabulary.
          examples:
            - antibody
        program_ids:
          items:
            type: integer
          type: array
          title: Program Ids
          description: >-
            The deal parties' programs of this drug (`GET
            /v1/programs/{program_id}`).
          examples:
            - - 3497
              - 3498
      type: object
      required:
        - drug_id
        - name
      title: DealAsset
    DealTarget:
      properties:
        term_id:
          type: string
          title: Term Id
          description: Ontology term identifier.
          examples:
            - NCIT:C18289
        term_label:
          type: string
          title: Term Label
          description: Human-readable ontology term label.
          examples:
            - Tumor Necrosis Factor Ligand Superfamily Member 15
        gene_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Gene Symbol
          description: HGNC symbol; null for a target with no single gene.
          examples:
            - TNFSF15
      type: object
      required:
        - term_id
        - term_label
      title: DealTarget
    DealTerms:
      properties:
        headline_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Total deal value as the sources state it.
        total_potential_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: '`headline_value` when stated, otherwise upfront plus milestones.'
        upfront:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Upfront consideration.
        equity:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Equity stake or investment.
        milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Milestone economics.
        royalties:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Royalty economics.
        territories:
          items:
            type: string
          type: array
          title: Territories
          description: Territories covered.
        rights_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Rights Summary
          description: Rights granted, in brief.
      type: object
      title: DealTerms
    DealEvent:
      properties:
        event_type:
          type: string
          enum:
            - proposed
            - announced
            - completed
            - amended
            - terminated
            - update
          title: Event Type
          description: Lifecycle event type.
        event_name:
          type: string
          title: Event Name
          description: Event headline.
        effective_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Effective At
          description: >-
            Event date (UTC day): the source's stated date, else its publication
            date.
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
          description: URL of the document that reported this event.
      type: object
      required:
        - event_type
        - event_name
      title: DealEvent
    DealSourceDocument:
      properties:
        source_vendor:
          type: string
          title: Source Vendor
          description: Publisher of the source document.
          examples:
            - sec
        source_kind:
          type: string
          title: Source Kind
          description: Document kind.
          examples:
            - sec_filing
        source_id:
          type: string
          title: Source Id
          description: Source-native document id.
          examples:
            - 0001999371-26-013429/ex99-1.htm
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
          description: Public URL of the document.
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
          description: Publication time (UTC).
        observed_at:
          type: string
          format: date-time
          title: Observed At
          description: When Pav first saw the document (UTC).
      type: object
      required:
        - source_vendor
        - source_kind
        - source_id
        - observed_at
      title: DealSourceDocument
    ErrorBody:
      properties:
        code:
          description: >-
            Stable, machine-readable error code (e.g. `unauthorized`,
            `not_found`, `validation_error`, `error`).
          examples:
            - not_found
          title: Code
          type: string
        message:
          description: Human-readable explanation of the error.
          examples:
            - program 999999 not found
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Correlation id echoed in the `X-Request-ID` response header. Quote
            it when contacting Pav support about a failed request.
          examples:
            - 3f2b9c1d8a7e4f6b9c0d1e2f3a4b5c6d
          title: Request Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
  securitySchemes:
    EnterpriseApiKey:
      type: http
      description: >-
        Use a personal or organization Pav API key from Pav developer settings.
        Send it as Authorization: Bearer <api_key>.
      scheme: bearer
      bearerFormat: Pav API key

````