Gong Entities API

openapi: 3.2.0
info:
  title: Gong Entities API
  description: 'Overview


    The Gong API allows you to:


    Receive the following information from Gong:


    Your company''s calls in Gong


    Your company''s users in Gong


    Your company''s user stats in Gong


    Your company''s user settings in Gong


    Your company''s libraries in Gong


    Upload new or

    update

    call recordings in Gong, in order to support cases where you have an internal system that records

    calls or obtains them from a third-party entity.


    Data Privacy:

    Delete users and all their associated elements.


    Upload CRM data into Gong.


    Check here what''s your base URL for all API calls.


    Authentication


    There are two ways to retrieve credentials to the Gong Public API:


    Retrieve Manually:


    In the Gong API Page (you

    must be a technical administrator in Gong), click "Create" to receive an Access Key

    and an Access Key Secret.


    Use the Basic Authorization HTTP header (as per RFC)

    to access the Public API as shown below:


    Authorization: Basic <token>


    To create the basic token, combine the Access Key and the Access Key Secret with

    colon (:) and then encode in Base64 as following:


    Base64(<accessKey> : <accessKeySecret>)


    Retrieve through OAuth


    To obtain the Bearer token, follow the steps described in the Gong OAuth Guide.


    After obtaining the token, use the Bearer Authorization HTTP header

    (as per RFC)

    to access the Public API as shown below:


    Authorization: Bearer <token>


    Limits


    By default Gong limits your company''s access to the service to 3 API calls per second, and 10,000 API calls per day.


    When the rate of API calls exceeds these limits an HTTP status code 429 is returned and a Retry-After header indicates

    how many seconds to wait before making a new request.


    If required, contact help.gong.io to change these limits.


    Cursors


    Some API calls that return a list are limited in the amount of records they may return, so multiple API calls may be

    required to bring all records. Such an API call also returns a records field, which contains the number of records

    in the current page, the current page number and the total number of records.


    In cases where the total number of records exceeds the number of records thus far retrieved, the records field will also

    contain a cursor field which can be used to access the next page of records. To retrieve the next page, repeat the API call with

    the cursor value as supplied by the previous API call. All other request inputs should remain the same.


    Forward Compatibility


    When coding a system to accept Gong data, take into account that Gong may, without prior warning, add fields to the JSON output.

    It is recommended to future proof your code so that it disregards all JSON fields you don''t actually use.'
  version: V2
servers:
- url: https://127.0.0.1:8443
  description: Generated server url
tags:
- name: Entities
  description: 'Gong''s “Entity” endpoints allow you to:


    Ask questions in natural language about CRM entities (accounts, contacts, deals, leads) and get AI-generated insights based on data from calls and emails.


    Generate pre-configured briefs on CRM entities. Briefs are set up in the Agent Studio in Gong.


    The response includes the generated answer or brief and the calls and emails used to generate it. It also includes information about the specific parts of those calls or emails that provided the evidence for the AI-generated content.'
paths:
  /v2/entities/get-brief:
    get:
      tags:
      - Entities
      summary: Generate a brief for a CRM entity (/v2/entities/get-brief)
      description: 'Get a brief for an account, deal, contact, or lead that exists in your CRM. Briefs are set up in the Gong Agent Studio and you must provide the name of the brief you want to generate. A call to this API consumes Gong credits according to the number of emails and calls used to generate the brief.

        The brief is generated from calls or emails associated with the entity within the specified time period.

        The response includes:


        The brief


        Details of emails and calls used to generate the brief


        Required authorization scope: ''api:ai-briefer:read''. Get AI-generated briefs for entities (Accounts, Deals, Contacts, Leads) using briefs configured in Gong.'
      operationId: generateBrief
      parameters:
      - name: workspaceId
        in: query
        description: Workspace identifier. The workspace the brief is defined in.
        required: true
        style: FORM
        explode: true
        schema:
          type: integer
          format: int64
          exampleSetFlag: false
          types:
          - integer
        example: 1237998047883638784
      - name: briefName
        in: query
        description: The name of the brief to generate. Briefs are configured in the Agent Studio > AI Briefer.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: Account overview
      - name: crmEntityType
        in: query
        description: The object type of the entity in the CRM.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
          enum:
          - ACCOUNT
          - CONTACT
          - DEAL
          - LEAD
        example: ACCOUNT
      - name: crmEntityId
        in: query
        description: The CRM Id of the entity the question is asked about.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: 125260001VdfoWBAR
      - name: timePeriod
        in: query
        description: Specifies the time period during which associated calls and emails must have occurred to be used to generate the answer. The calls and emails must be associated with the specified entity.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
          enum:
          - LAST_7DAYS
          - LAST_30DAYS
          - LAST_90DAYS
          - LAST_90_DAYS_SINCE_LAST_ACTIVITY
          - LAST_YEAR_SINCE_LAST_ACTIVITY
          - LAST_YEAR
          - THIS_WEEK
          - THIS_MONTH
          - THIS_YEAR
          - THIS_QUARTER
          - CUSTOM_RANGE
          - ALL_CONVERSATIONS
        example: CUSTOM_RANGE
      - name: fromDateTime
        in: query
        description: 'Required when timePeriod is CUSTOM_RANGE

          Specifies the date and time (UTC) on or after which calls (based on call start time) and emails must have occurred to be included when generating the answer.

          Date and time (in ISO-8601 format: ''2024-10-18T08:00:00Z'', where Z stands for UTC).'
        required: false
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: '2024-01-01T00:00:00Z'
      - name: toDateTime
        in: query
        description: 'Relevant only when timePeriod is CUSTOM_RANGE

          Specifies the date and time (UTC) before which calls (based on call start time) and emails must have occurred to be included when generating the answer.

          Date and time (in ISO-8601 format: ''2024-10-18T08:00:00Z'', where Z stands for UTC).'
        required: false
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateBriefResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '400':
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '401':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '429':
          description: API request limit exceeded
          headers:
            Retry-After:
              description: Number of seconds to wait before making a new request.
              style: SIMPLE
              explode: false
              schema:
                type: integer
                format: int32
                exampleSetFlag: false
                types:
                - integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '500':
          description: Failed to complete the operation due to an unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
  /v2/entities/ask-entity:
    get:
      tags:
      - Entities
      summary: Ask about an entity (/v2/entities/ask-entity)
      description: 'Returns the answer to a question about a specified entity. The answer is generated from calls or emails associated with the entity within the specified time period. A maximum of 60 calls and 500 emails are used to answer the question. A call to this API consumes Gong credits according to the number of emails and calls used to generate the answer.

        Supported entities are Accounts, Deals, Contacts, or Leads that exist in your CRM.

        The response includes:


        The answer


        Details of emails and calls used to generate the answer


        Required authorization scope: ''api:ai-ask:read''. Get AI-generated answers to natural language questions about entities (Accounts, Deals, Contacts, Leads).'
      operationId: askEntity
      parameters:
      - name: workspaceId
        in: query
        description: Workspace identifier. The calls and emails used to answer the question must be associated with this workspace.
        required: true
        style: FORM
        explode: true
        schema:
          type: integer
          format: int64
          exampleSetFlag: false
          types:
          - integer
        example: 1237998047883638784
      - name: crmEntityType
        in: query
        description: The object type of the entity in the CRM.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
          enum:
          - ACCOUNT
          - CONTACT
          - DEAL
          - LEAD
        example: ACCOUNT
      - name: crmEntityId
        in: query
        description: The CRM Id of the entity the question is asked about.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: 125260001VdfoWBAR
      - name: timePeriod
        in: query
        description: Specifies the time period during which associated calls and emails must have occurred to be used to generate the answer. The calls and emails must be associated with the specified entity.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
          enum:
          - LAST_7DAYS
          - LAST_30DAYS
          - LAST_90DAYS
          - LAST_90_DAYS_SINCE_LAST_ACTIVITY
          - LAST_YEAR_SINCE_LAST_ACTIVITY
          - LAST_YEAR
          - THIS_WEEK
          - THIS_MONTH
          - THIS_YEAR
          - THIS_QUARTER
          - CUSTOM_RANGE
          - ALL_CONVERSATIONS
        example: CUSTOM_RANGE
      - name: fromDateTime
        in: query
        description: 'Required when timePeriod is CUSTOM_RANGE

          Specifies the date and time (UTC) on or after which calls (based on call start time) and emails must have occurred to be included when generating the answer.

          Date and time (in ISO-8601 format: ''2024-10-18T08:00:00Z'', where Z stands for UTC).'
        required: false
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: '2024-01-01T00:00:00Z'
      - name: toDateTime
        in: query
        description: 'Relevant only when timePeriod is CUSTOM_RANGE

          Specifies the date and time (UTC) before which calls (based on call start time) and emails must have occurred to be included when generating the answer.

          Date and time (in ISO-8601 format: ''2024-10-18T08:00:00Z'', where Z stands for UTC).'
        required: false
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: '2024-12-31T23:59:59Z'
      - name: question
        in: query
        description: The question to answer.
        required: true
        style: FORM
        explode: true
        schema:
          type: string
          exampleSetFlag: false
          types:
          - string
        example: What was the last activity on that account?
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskEntityResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '400':
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '401':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '429':
          description: API request limit exceeded
          headers:
            Retry-After:
              description: Number of seconds to wait before making a new request.
              style: SIMPLE
              explode: false
              schema:
                type: integer
                format: int32
                exampleSetFlag: false
                types:
                - integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '500':
          description: Failed to complete the operation due to an unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
components:
  schemas:
    WebFindingDto:
      type: object
      properties:
        domain:
          type: string
          description: The domain of the website. This domain might be a Gong or a third-party URL that redirects (HTTP 302) to the original website.
          exampleSetFlag: false
          types:
          - string
        title:
          type: string
          description: The title of the web page
          exampleSetFlag: false
          types:
          - string
        url:
          type: string
          description: The web page URL
          exampleSetFlag: false
          types:
          - string
      description: Evidence from results of a web search used to generate the brief for this section.
      exampleSetFlag: false
      types:
      - object
    EmailInfoDto:
      type: object
      properties:
        id:
          type: string
          description: The email Id. This Id can be used to view the email in Gong by adding it to a Gong URL.
          example: 5gfz1gfshfhqdfgsaghhjvcah
          exampleSetFlag: true
          types:
          - string
        title:
          type: string
          description: The email subject
          example: Acme Legal/Compliance Needs
          exampleSetFlag: true
          types:
          - string
        sentDateTime:
          type: string
          description: 'The date and time the email message was sent in the ISO-8601 format, for example: ''2024-01-17T16:20:05-03:00'' or ''2016-02-16T03:57:04.834+05:30'' or ''2020-11-20T21:30:07.233692Z'', where Z stands for UTC.'
          format: date-time
          example: 1705519205.0
          exampleSetFlag: true
          types:
          - string
      description: Details of the emails that contain supporting evidence.
      exampleSetFlag: false
      types:
      - object
    CallInfoDto:
      type: object
      properties:
        id:
          type: string
          description: The call ID
          example: '123454809855576620'
          exampleSetFlag: true
          types:
          - string
        title:
          type: string
          description: The call title
          example: Gong + Acme Bi-Weekly
          exampleSetFlag: true
          types:
          - string
        started:
          type: string
          description: The date and time the call was recorded in the ISO-8601 format (e.g., '2018-02-18T02:30:00-07:00' or '2018-02-18T08:00:00Z', where Z stands for UTC).
          format: date-time
          example: 1718461800.0
          exampleSetFlag: true
          types:
          - string
        url:
          type: string
          description: Link to the call page in Gong
          example: https://gong.app.gong.io/call?id=123454809855576620
          exampleSetFlag: true
          types:
          - string
      description: Details of the call that contains supporting evidence for the answer.
      exampleSetFlag: false
      types:
      - object
    McpResultDto:
      type: object
      properties:
        connections:
          type: array
          description: Connection result for each MCP connection
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/ConnectionResultDto'
            exampleSetFlag: false
          types:
          - array
        servers:
          type: array
          description: Set of server names that were invoked during the execution.
          exampleSetFlag: false
          items:
            type: string
            example: Sentry MCP
            exampleSetFlag: true
            types:
            - string
          types:
          - array
        mcpStatus:
          type: string
          description: Overall execution status
          example: CONNECTION_ERROR
          exampleSetFlag: true
          types:
          - string
          enum:
          - SUCCESS
          - FAILURE
          - CONNECTION_ERROR
        errorMessage:
          type: string
          description: Overall error message (dropped when status is SUCCESS)
          example: Failed to establish one or more required connections. Verify the connection and try again.
          exampleSetFlag: true
          types:
          - string
      description: Result returned from MCP connections defined for this brief section. Only relevant when briefSectionType is McpConnection.
      exampleSetFlag: false
      types:
      - object
    GenerateBriefResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.
          example: 4al018gzaztcr8nbukw
          exampleSetFlag: true
          types:
          - string
        numOfCallsSearched:
          type: integer
          description: Number of calls searched to generate the brief
          format: int32
          example: 7
          exampleSetFlag: true
          types:
          - integer
        numOfEmailsSearched:
          type: integer
          description: Number of emails searched to generate the brief
          format: int32
          example: 102
          exampleSetFlag: true
          types:
          - integer
        briefSections:
          type: array
          description: The sections defined for the brief
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/BriefSectionDto'
            exampleSetFlag: false
          types:
          - array
      exampleSetFlag: false
      types:
      - object
    AnswerSectionDto:
      type: object
      properties:
        answerItems:
          type: array
          description: An array of items that make up the answer. Each item contains part of the generated response and metadata describing the calls and emails used as sources.
          exampleSetFlag: false
          items:
            type: string
            example: Acme has questions about compliance.
            exampleSetFlag: true
            types:
            - string
          types:
          - array
        emailFindings:
          type: array
          description: Evidence from emails used. Includes the relevant emails and the supporting excerpts identified.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/EmailFindingDto'
            exampleSetFlag: false
          types:
          - array
        callFindings:
          type: array
          description: Evidence from calls used to generate this answer item. Includes the relevant calls and supporting excerpts.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/EntityCallFindingDto'
            exampleSetFlag: false
          types:
          - array
      description: The generated answer. The answer is composed of one or more answerItems, each representing a portion of the response along with the calls and emails used to generate it.
      exampleSetFlag: false
      types:
      - object
    BriefCallFindingDto:
      type: object
      properties:
        call:
          $ref: '#/components/schemas/CallInfoDto'
          exampleSetFlag: false
      description: Evidence from calls used to generate this section of the brief. Includes the relevant calls and the supporting excerpts identified in them.
      exampleSetFlag: false
      types:
      - object
    EmailFindingDto:
      type: object
      properties:
        emails:
          type: array
          description: Details of the emails that contain supporting evidence.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/EmailInfoDto'
            exampleSetFlag: false
          types:
          - array
      description: Evidence from emails used. Includes the relevant emails and the supporting excerpts identified.
      exampleSetFlag: false
      types:
      - object
    AskEntityResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.
          example: 4al018gzaztcr8nbukw
          exampleSetFlag: true
          types:
          - string
        numOfCallsSearched:
          type: integer
          description: Number of calls searched to generate the answer
          format: int32
          example: 25
          exampleSetFlag: true
          types:
          - integer
        numOfEmailsSearched:
          type: integer
          description: Number of emails searched to generate the answer
          format: int32
          example: 252
          exampleSetFlag: true
          types:
          - integer
        answer:
          type: array
          description: The generated answer. The answer is composed of one or more answerItems, each representing a portion of the response along with the calls and emails used to generate it.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/AnswerSectionDto'
            exampleSetFlag: false
          types:
          - array
      exampleSetFlag: false
      types:
      - object
    ConnectionResultDto:
      type: object
      properties:
        name:
          type: string
          description: The name given to the MCP connection in Gong
          example: Sentry
          exampleSetFlag: true
          types:
          - string
        status:
          type: string
          description: The status of the MCP connection
          example: NOT_CONNECTED
          exampleSetFlag: true
          types:
          - string
          enum:
          - SUCCESS
          - AUTH_REQUIRED
          - FAILED
          - NOT_CONNECTED
          - NO_MATCHING_TOOLS
          - NO_USER_CONTEXT
          - UNKNOWN
      description: Connection result for each MCP connection
      exampleSetFlag: false
      types:
      - object
    ErrorResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.
          example: 4al018gzaztcr8nbukw
          exampleSetFlag: true
          types:
          - string
        errors:
          type: array
          description: Error messages.
          example:
          - An error has occurred
          exampleSetFlag: true
          items:
            type: string
            exampleSetFlag: false
            types:
            - string
          types:
          - array
      exampleSetFlag: false
      types:
      - object
    BriefSectionDto:
      type: object
      properties:
        title:
          type: string
          description: Section title (omitted if null)
          example: Customer overview
          exampleSetFlag: true
          types:
          - string
        sectionSummary:
          type: array
          description: The content displayed for this section.
          exampleSetFlag: false
          items:
            type: string
            example: Acme is involved in customer service.
            exampleSetFlag: true
            types:
            - string
          types:
          - array
        conversationFindings:
          $ref: '#/components/schemas/ConversationFindingsDto'
          exampleSetFlag: false
        briefSectionType:
          type: string
          description: The section type. Determines the source of the data, and what type of data is included in the section.
          example: Conversations
          exampleSetFlag: true
          types:
          - string
          enum:
          - Conversations
          - Web
          - CrmOrGongData
          - McpConnection
        webFindings:
          type: array
          description: Evidence from results of a web search used to generate the brief for this section.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/WebFindingDto'
            exampleSetFlag: false
          types:
          - array
        mcpResult:
          $ref: '#/components/schemas/McpResultDto'
          exampleSetFlag: false
      description: The sections defined for the brief
      exampleSetFlag: false
      types:
      - object
    ConversationFindingsDto:
      type: object
      properties:
        callFindings:
          type: array
          description: Evidence from calls used to generate this section of the brief. Includes the relevant calls and the supporting excerpts identified in them.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/BriefCallFindingDto'
            exampleSetFlag: false
          types:
          - array
        emailFindings:
          type: array
          description: Evidence from emails used to generate this section in the brief. Includes the relevant emails and the supporting excerpts identified in them.
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/EmailFindingDto'
            exampleSetFlag: false
          types:
          - array
      description: Evidence from calls and emails used to generate this section of the brief. Includes the relevant calls and emails and the supporting excerpts identified in them. Only relevant when briefSectionType is Conversations.
      exampleSetFlag: false
      types:
      - object
    EntityCallFindingDto:
      type: object
      properties:
        call:
          $ref: '#/components/schemas/CallInfoDto'
          exampleSetFlag: false
      description: Evidence from calls used to generate this answer item. Includes the relevant calls and supporting excerpts.
      exampleSetFlag: false
      types:
      - object
x-provenance:
  method: harvested
  publisher: Gong
  source: https://app.gong.io/ajax/settings/api/documentation/specs?version=
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)