HubSpot CRM Notetaker Conversation Recap API

openapi: 3.0.1
info:
  title: HubSpot CRM Notetaker Conversation Recap
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
paths:
  /notetaker/2026-09/conversation/recap/{objectTypeId}/{objectId}:
    get:
      tags:
      - Basic
      summary: Retrieve conversation recap data
      description: Retrieve a recap of a conversation based on the specified object type and object ID.
        This endpoint provides a variety of insights related to the conversation, including summary, action
        items, questions asked, call stats, participants, and recording URL.
      operationId: get-/notetaker/2026-09/conversation/recap/{objectTypeId}/{objectId}
      parameters:
      - name: objectId
        in: path
        description: The unique identifier of the object for which the conversation recap is being retrieved.
          This is a required integer parameter.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: objectTypeId
        in: path
        description: The type of the object for which the conversation recap is being retrieved. This
          is a required string parameter.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationRecapResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.contacts.highly_sensitive.read.v2
      - oauth2:
        - crm.objects.contacts.sensitive.read.v2
      - oauth2:
        - crm.schemas.contacts.read
      - oauth2:
        - crm.objects.contacts.read
components:
  schemas:
    ActionItem:
      required:
      - id
      - title
      type: object
      properties:
        assignee:
          type: string
          description: A string indicating the individual assigned to the action item. This property is
            optional.
        assigneeObjectId:
          type: string
          description: The id of the HubSpot user or contact assigned to this action item, if found. This
            property is optional.
        id:
          type: string
          description: The unique identifier for the action item, represented as a string.
        title:
          type: string
          description: A string representing the title or main description of the action item. This property
            is required.
    ConversationRecapActionItemsResult:
      required:
      - items
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        items:
          type: array
          description: The list of action items extracted from the conversation. Populated when status
            is SUCCEEDED; empty otherwise.
          items:
            $ref: '#/components/schemas/ActionItem'
        status:
          type: string
          description: The current state of action item generation. SUCCEEDED — action items are available.
            NOT_FOUND — no action items have been generated for this engagement. IN_PROGRESS — generation
            is currently underway. FAILED — an error occurred while retrieving action items.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
    ConversationRecapCallStatsResult:
      required:
      - hasTranscript
      - status
      type: object
      properties:
        durationMs:
          type: integer
          description: The length of the recorded conversation in milliseconds.
          format: int64
        error:
          $ref: '#/components/schemas/StandardError'
        hasTranscript:
          type: boolean
          description: Whether a transcript for a conversation is found.
        ownerTalkTimePercentage:
          type: string
          description: The percentage of talk-time attributed to the owner participant.
        status:
          type: string
          description: The status of fetching call stats. Either SUCCEEDED, NOT_FOUND, or FAILED.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
    ConversationRecapNotesResult:
      required:
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        status:
          type: string
          description: The status of fetching the notes. Either SUCCEEDED, NOT_FOUND, or FAILED.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
        value:
          type: string
          description: A string containing the notes from the conversation recap.
    ConversationRecapParticipantsResult:
      required:
      - items
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        items:
          type: array
          description: An array of participant information objects, each containing details about a participant
            in the conversation.
          items:
            $ref: '#/components/schemas/ParticipantInfo'
        status:
          type: string
          description: The status of fetching participants. Either SUCCEEDED or FAILED.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
    ConversationRecapQuestionsAskedResult:
      required:
      - questionsAndAnswers
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        questionsAndAnswers:
          type: array
          description: 'A list of question and answer pairs. '
          items:
            $ref: '#/components/schemas/QuestionAndAnswer'
        status:
          type: string
          description: The status of fetching questions and answers. Either FAILED, NOT_FOUND, or SUCCEEDED.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
    ConversationRecapRecordingUrlResult:
      required:
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        status:
          type: string
          description: The status of creating a URL. Either FAILED, NOT_FOUND, or SUCCEEDED.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
        value:
          type: string
          description: The URL of the recording as a string.
    ConversationRecapResponse:
      required:
      - actionItems
      - callStats
      - notes
      - participants
      - questionsAsked
      - recordingUrl
      type: object
      properties:
        actionItems:
          $ref: '#/components/schemas/ConversationRecapActionItemsResult'
        callStats:
          $ref: '#/components/schemas/ConversationRecapCallStatsResult'
        notes:
          $ref: '#/components/schemas/ConversationRecapNotesResult'
        participants:
          $ref: '#/components/schemas/ConversationRecapParticipantsResult'
        questionsAsked:
          $ref: '#/components/schemas/ConversationRecapQuestionsAskedResult'
        recordingUrl:
          $ref: '#/components/schemas/ConversationRecapRecordingUrlResult'
        summary:
          $ref: '#/components/schemas/ConversationRecapSummaryResult'
    ConversationRecapSummaryResult:
      required:
      - status
      type: object
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
        status:
          type: string
          description: The current state of summary generation. SUCCEEDED — summary is available. NOT_FOUND
            — no summary has been generated for this engagement. FAILED — an error occurred while retrieving
            the summary.
          enum:
          - FAILED
          - IN_PROGRESS
          - NOT_FOUND
          - NOT_SUPPORTED
          - SUCCEEDED
        value:
          type: string
          description: The AI-generated summary text for the conversation. Present when status is SUCCEEDED;
            absent otherwise.
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category, represented as a string.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object providing context about the error condition, where each property is an
            array of strings.
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request, used for tracking and support purposes. It
            is a string in UUID format.
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: An array containing further information about the error, with each item being an
            ErrorDetail object.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error
            or recommended remediation steps. Each link is represented as a string.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate. It is a string.
          example: An error occurred
        subCategory:
          type: string
          description: A specific category providing more detailed information about the error. It is
            a string.
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail. This helps identify the type
            of error that occurred.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object providing context about the error condition. It contains additional properties
            that offer more details, such as missing scopes or other relevant information.
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found. It provides context
            about the location of the error.
        message:
          type: string
          description: A human-readable message describing the error along with remediation steps where
            appropriate. This is a required field.
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error. It offers
            further classification of the error.
      description: Represents detailed information about an error that occurred in the API. This component
        is used to provide additional context and specifics about errors, typically as part of an error
        response.
    ParticipantInfo:
      required:
      - isHost
      - name
      type: object
      properties:
        email:
          type: string
          description: The email address of the participant. Only present when the participant is a HubSpot
            Contact.
        isHost:
          type: boolean
          description: Whether this participant was the host of the conversation.
        name:
          type: string
          description: 'The name of the participant. '
        phoneNumber:
          type: string
          description: The phone number of the participant. Only present when the participant is a HubSpot
            Contact.
    QuestionAndAnswer:
      required:
      - question
      type: object
      properties:
        answer:
          $ref: '#/components/schemas/SpeakerStatement'
        question:
          $ref: '#/components/schemas/SpeakerStatement'
    SpeakerStatement:
      type: object
      properties:
        speakerName:
          type: string
          description: The speaker attributed to this statement.
        text:
          type: string
          description: The time at which this statement occurred.
        timestampSeconds:
          type: number
          description: The time in a recorded conversation at which this statement occurred.
    StandardError:
      required:
      - category
      - context
      - errors
      - links
      - message
      - status
      type: object
      properties:
        category:
          type: string
          description: A string representing the category of the error.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: An object containing additional context about the error condition, where each key
            maps to an array of strings.
        errors:
          type: array
          description: An array of ErrorDetail objects providing further information about the error.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        id:
          type: string
          description: A string that serves as a unique identifier for the error instance.
        links:
          type: object
          additionalProperties:
            type: string
          description: An object mapping link names to associated URIs that contain documentation or recommended
            remediation steps related to the error.
        message:
          type: string
          description: A string containing a human-readable message describing the error.
        status:
          type: string
          description: A string representing the status of the error.
        subCategory:
          type: object
          properties: {}
          description: An object providing more specific details about the error category.
      description: Ye olde error
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            crm.objects.contacts.highly_sensitive.read.v2: ''
            crm.objects.contacts.read: ''
            crm.objects.contacts.sensitive.read.v2: ''
            crm.schemas.contacts.read: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: FREE
  service: FREE
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE