Gong Calls API

openapi: 3.2.0
info:
  title: Gong Calls API
  description: The Gong Calls API provides endpoints to retrieve, add, and manage call data including recordings, transcripts, and media files. It supports filtering calls by date range, retrieving detailed call analytics, and uploading call recordings from external telephony systems.
  version: 2.0.0
  contact:
    name: Gong
    url: https://www.gong.io
    email: support@gong.io
  license:
    name: Proprietary
    url: https://www.gong.io/terms-of-service/
  termsOfService: https://www.gong.io/terms-of-service/
servers:
- url: https://api.gong.io/v2
  description: Gong API v2 Production Server
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Calls
  description: Operations for managing and retrieving call data
paths:
  /calls:
    get:
      operationId: listCalls
      summary: Gong List calls
      description: Retrieves a list of calls that took place during a specified date range. Results are paginated and can be filtered by workspace.
      tags:
      - Calls
      parameters:
      - name: fromDateTime
        in: query
        required: true
        description: The start date and time for the calls filter in ISO-8601 format (e.g., 2021-01-01T00:00:00Z).
        schema:
          type: string
          format: date-time
      - name: toDateTime
        in: query
        required: true
        description: The end date and time for the calls filter in ISO-8601 format (e.g., 2021-12-31T23:59:59Z).
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        required: false
        description: A cursor for pagination. Pass the cursor from the previous response to retrieve the next page of results.
        schema:
          type: string
      - name: workspaceId
        in: query
        required: false
        description: Optional workspace identifier to filter calls by workspace.
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing a list of calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallsResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: addCall
      summary: Gong Add a new call
      description: Adds a new call record to Gong. Either provide a downloadMediaUrl in the request body or use the returned callId in a follow-up request to /v2/calls/{id}/media to upload the media file.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCallAddingRequest'
      responses:
        '201':
          description: Call successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewCallAddingResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /calls/{id}:
    get:
      operationId: getCall
      summary: Gong Retrieve a specific call
      description: Retrieves detailed information about a specific call identified by its unique numeric identifier.
      tags:
      - Calls
      parameters:
      - name: id
        in: path
        required: true
        description: Gong's unique numeric identifier for the call (up to 20 digits).
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the call details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecificCallResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Call not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /calls/extensive:
    post:
      operationId: listCallsExtensive
      summary: Gong Retrieve detailed call data
      description: Retrieves extensive call data including participants, topics, trackers, comments, scorecards, and other analytics. Supports filtering by date range, call IDs, or hosting users. Requires the scope api:calls:read:extensive.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtensiveCallsRequest'
      responses:
        '200':
          description: Successful response containing detailed call data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensiveCallsResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /calls/manual-crm-associations:
    get:
      operationId: listManualCrmAssociations
      summary: Gong List calls manually associated with CRM
      description: Retrieves a list of calls that were manually associated with CRM objects by users. This endpoint is in beta phase. Results can be filtered by association time.
      tags:
      - Calls
      parameters:
      - name: fromDateTime
        in: query
        required: false
        description: Filter by the time the manual association was created, in ISO-8601 format.
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        required: false
        description: A cursor for pagination. Pass the cursor from the previous response to retrieve the next page of results.
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing a list of manually associated calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManualAssociationResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /calls/users-access:
    post:
      operationId: retrieveUserCallAccess
      summary: Gong Retrieve user call access
      description: Retrieves the list of users who have access to specified calls and their access levels.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCallAccessRequest'
      responses:
        '200':
          description: Successful response containing user call access data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCallAccessResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: giveUserCallAccess
      summary: Gong Give user call access
      description: Grants specified users access to specified calls within the Gong platform.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCallAccessUpdateRequest'
      responses:
        '200':
          description: Call access successfully granted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: removeUserCallAccess
      summary: Gong Remove user call access
      description: Removes specified users' access to specified calls within the Gong platform.
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCallAccessUpdateRequest'
      responses:
        '200':
          description: Call access successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '401':
          description: Unauthorized - invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DetailedCall:
      allOf:
      - $ref: '#/components/schemas/Call'
      - type: object
        properties:
          content:
            type: object
            properties:
              topics:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    duration:
                      type: number
                description: Topics discussed during the call.
              trackers:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    count:
                      type: integer
                    occurrences:
                      type: array
                      items:
                        type: object
                        properties:
                          startTime:
                            type: number
                          speakerId:
                            type: string
                description: Tracked keywords and phrases.
              pointsOfInterest:
                type: object
                properties:
                  actionItems:
                    type: array
                    items:
                      type: object
                      properties:
                        snippet:
                          type: string
                        speakerId:
                          type: string
                description: Key points and action items.
            description: Content analysis data.
          collaboration:
            type: object
            properties:
              publicComments:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    commenterUserId:
                      type: string
                    comment:
                      type: string
                    audioStartTime:
                      type: number
                    posted:
                      type: string
                      format: date-time
                description: Public comments on the call.
            description: Collaboration data.
          interaction:
            type: object
            properties:
              speakers:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    userId:
                      type: string
                    talkTime:
                      type: number
                description: Speaker statistics.
              interactivity:
                type: number
                description: Interactivity score.
            description: Interaction statistics.
          media:
            type: object
            properties:
              audioUrl:
                type: string
                format: uri
                description: URL for the audio recording.
              videoUrl:
                type: string
                format: uri
                description: URL for the video recording.
            description: Media URLs for the call recording.
    UserCallAccessUpdateRequest:
      type: object
      properties:
        callIds:
          type: array
          items:
            type: string
          description: List of call IDs to update access for.
        userIds:
          type: array
          items:
            type: string
          description: List of user IDs to grant or revoke access.
    ManualAssociationResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        records:
          type: object
          properties:
            totalRecords:
              type: integer
            currentPageSize:
              type: integer
            cursor:
              type: string
        calls:
          type: array
          items:
            type: object
            properties:
              callId:
                type: string
                description: The call ID.
              crmAssociations:
                type: array
                items:
                  type: object
                  properties:
                    objectType:
                      type: string
                    objectId:
                      type: string
                    associatedAt:
                      type: string
                      format: date-time
          description: Calls with their manual CRM associations.
    NewCallAddingResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        callId:
          type: string
          description: The Gong-assigned unique identifier for the newly created call.
    NewCallAddingRequest:
      type: object
      required:
      - actualStart
      - clientUniqueId
      - direction
      - parties
      - primaryUser
      properties:
        actualStart:
          type: string
          format: date-time
          description: The actual start time of the call in ISO-8601 format.
        clientUniqueId:
          type: string
          description: A unique identifier for the call provided by the client to prevent duplicates.
        direction:
          type: string
          enum:
          - Inbound
          - Outbound
          - Conference
          - Unknown
          description: The direction of the call.
        downloadMediaUrl:
          type: string
          format: uri
          description: Optional URL from which Gong can download the call recording media. If not provided, use /v2/calls/{id}/media to upload.
        duration:
          type: number
          description: Duration of the call in seconds.
        languageCode:
          type: string
          description: Language code of the call for transcription.
        meetingUrl:
          type: string
          format: uri
          description: URL of the meeting (if applicable).
        parties:
          type: array
          items:
            $ref: '#/components/schemas/NewCallParty'
          description: List of call participants.
        primaryUser:
          type: string
          description: Email address of the primary Gong user on the call.
        purpose:
          type: string
          description: The purpose or subject of the call.
        scheduledEnd:
          type: string
          format: date-time
          description: The scheduled end time of the call.
        scheduledStart:
          type: string
          format: date-time
          description: The scheduled start time of the call.
        title:
          type: string
          description: The title of the call.
        workspaceId:
          type: string
          description: The workspace to associate the call with.
    UserCallAccessRequest:
      type: object
      properties:
        callIds:
          type: array
          items:
            type: string
          description: List of call IDs to check access for.
    NewCallParty:
      type: object
      properties:
        emailAddress:
          type: string
          format: email
          description: Email address of the participant.
        name:
          type: string
          description: Display name of the participant.
        phoneNumber:
          type: string
          description: Phone number of the participant.
        userId:
          type: string
          description: Gong user ID of the participant (if applicable).
    ErrorResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        errors:
          type: array
          items:
            type: string
          description: List of error messages.
    CallsResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        records:
          type: object
          properties:
            totalRecords:
              type: integer
              description: Total number of call records matching the filter.
            currentPageSize:
              type: integer
              description: Number of records in the current page.
            currentPageNumber:
              type: integer
              description: The current page number.
            cursor:
              type: string
              description: Cursor value for retrieving the next page of results.
        calls:
          type: array
          items:
            $ref: '#/components/schemas/Call'
          description: List of call objects.
    CallParty:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the party.
        emailAddress:
          type: string
          format: email
          description: Email address of the party.
        name:
          type: string
          description: Display name of the party.
        title:
          type: string
          description: Job title of the party.
        userId:
          type: string
          description: Gong user ID if the party is a Gong user.
        speakerId:
          type: string
          description: Speaker identifier within the call.
        affiliation:
          type: string
          enum:
          - Internal
          - External
          - Unknown
          description: Whether the party is internal or external.
        phoneNumber:
          type: string
          description: Phone number of the party.
        methods:
          type: array
          items:
            type: string
          description: Communication methods used by the party.
    UserCallAccessResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        callAccessDetails:
          type: array
          items:
            type: object
            properties:
              callId:
                type: string
              userIds:
                type: array
                items:
                  type: string
          description: Access details for each call.
    ExtensiveCallsResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        records:
          type: object
          properties:
            totalRecords:
              type: integer
              description: Total number of matching records.
            currentPageSize:
              type: integer
              description: Number of records in the current page.
            cursor:
              type: string
              description: Cursor for retrieving the next page.
        calls:
          type: array
          items:
            $ref: '#/components/schemas/DetailedCall'
          description: List of detailed call objects.
    Call:
      type: object
      properties:
        id:
          type: string
          description: Unique numeric identifier for the call.
        title:
          type: string
          description: The title or subject of the call.
        url:
          type: string
          format: uri
          description: URL to the call in the Gong web application.
        scheduled:
          type: string
          format: date-time
          description: Scheduled start time of the call in ISO-8601 format.
        started:
          type: string
          format: date-time
          description: Actual start time of the call in ISO-8601 format.
        duration:
          type: number
          description: Duration of the call in seconds.
        direction:
          type: string
          enum:
          - Inbound
          - Outbound
          - Conference
          - Unknown
          description: The direction of the call.
        scope:
          type: string
          enum:
          - Internal
          - External
          - Unknown
          description: Whether the call was internal or external.
        media:
          type: string
          enum:
          - Video
          - Audio
          description: The type of media recorded.
        language:
          type: string
          description: The detected language of the call.
        workspaceId:
          type: string
          description: The workspace identifier the call belongs to.
        primaryUserId:
          type: string
          description: The Gong user ID of the primary user on the call.
        parties:
          type: array
          items:
            $ref: '#/components/schemas/CallParty'
          description: The participants in the call.
    SpecificCallResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
        call:
          $ref: '#/components/schemas/Call'
    BaseResponse:
      type: object
      properties:
        requestId:
          type: string
          description: A unique identifier for the request.
    ExtensiveCallsRequest:
      type: object
      properties:
        cursor:
          type: string
          description: Cursor for pagination.
        filter:
          type: object
          properties:
            fromDateTime:
              type: string
              format: date-time
              description: Start of the date range filter.
            toDateTime:
              type: string
              format: date-time
              description: End of the date range filter.
            callIds:
              type: array
              items:
                type: string
              description: Specific call IDs to retrieve.
            workspaceId:
              type: string
              description: Filter by workspace.
          description: Filter criteria for calls.
        contentSelector:
          type: object
          properties:
            context:
              type: string
              enum:
              - None
              - Extended
              - Full
              description: Level of context to include.
            exposedFields:
              type: object
              properties:
                collaboration:
                  type: boolean
                  description: Include collaboration data.
                content:
                  type: boolean
                  description: Include content data.
                currentSpeakerUserIds:
                  type: boolean
                  description: Include speaker user IDs.
                media:
                  type: boolean
                  description: Include media URLs (requires api:calls:read:media-url scope).
                parties:
                  type: boolean
                  description: Include party information.
                publicComments:
                  type: boolean
                  description: Include public comments.
              description: Fields to include in the response.
          description: Selector for what content to include in the response.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Basic authentication using your Gong API access key and secret. Format: base64(access_key:access_secret).'
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token authentication.