Gong Targets API

openapi: 3.2.0
info:
  title: Gong Targets 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: Targets
paths:
  /v2/targets/{targetId}/assignments:
    post:
      tags:
      - Targets
      summary: Upload target assignments (/v2/targets/{targetId}/assignments)
      description: 'Uploads target assignments from a CSV file. Use validateOnly=true to validate your file without writing data. If validation fails, nothing is written regardless of validateOnly. Maximum 10,000 data rows per request (excluding header).

        When accessed through a Bearer token authorization method, this endpoint requires the scope ''api:targets:write''.'
      operationId: uploadAssignments
      parameters:
      - name: targetId
        in: path
        description: Unique identifier for the target (up to 20 digits). Retrieve this value using the List targets API.
        required: true
        style: SIMPLE
        explode: false
        schema:
          type: integer
          format: int64
          exampleSetFlag: false
          types:
          - integer
      - name: workspaceId
        in: query
        description: The ID of the workspace the target belongs to. You can retrieve workspace IDs using the Workspaces API.
        required: true
        style: FORM
        explode: true
        schema:
          type: integer
          format: int64
          exampleSetFlag: false
          types:
          - integer
      - name: validateOnly
        in: query
        description: '(Default: false) When true, the CSV file is fully validated but no data is uploaded. Use this to check your file for errors before committing.'
        required: false
        style: FORM
        explode: true
        schema:
          type: boolean
          exampleSetFlag: false
          types:
          - boolean
          default: false
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              type: object
              properties:
                file:
                  type: string
                  description: CSV file of target assignments. Maximum 10,000 data rows (excluding header).
                  format: binary
                  exampleSetFlag: false
                  types:
                  - string
              exampleSetFlag: false
              types:
              - object
            exampleSetFlag: false
      responses:
        '200':
          description: Validation passed. If validateOnly is false, assignments were written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetAssignmentsResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '400':
          description: CSV validation errors, missing/invalid parameters, or CSV exceeds 10,000 rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '404':
          description: targetDefinitionId not found in the specified workspace
          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/targets:
    get:
      tags:
      - Targets
      summary: List target definitions (/v2/targets)
      description: 'Returns all target definitions configured for the specified workspace. Targets are performance goals, such as revenue quotas or deal counts, that admins configure in the Data studio. Each target definition includes a hierarchy type that determines how assignments are structured: team hierarchy assigns targets to individual team members or team rollups, while territory hierarchy assigns targets to territory nodes. Use this endpoint to get the list of targets in your workspace before uploading assignments, and to retrieve the fields you need to prepare a correctly formatted CSV file.

        A successful response returns a list of target definitions. If the list is empty, the specified workspace has no defined targets.

        Required authorization scope: ''api:targets:read''.'
      operationId: listTargetDefinitions
      parameters:
      - name: workspaceId
        in: query
        description: The ID of the workspace to retrieve target definitions for. You can retrieve workspace IDs using the Workspaces API.
        required: true
        style: FORM
        explode: true
        schema:
          type: integer
          format: int64
          exampleSetFlag: false
          types:
          - integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetDefinitionsResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '400':
          description: workspaceId is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                exampleSetFlag: false
              exampleSetFlag: false
        '403':
          description: Access denied
          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:
    TargetAssignmentsResponse:
      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
        validateOnly:
          type: boolean
          description: Indicates whether this was a validation-only request. No data is uploaded if true.
          exampleSetFlag: false
          types:
          - boolean
        processedRows:
          type: integer
          description: The number of rows validated (when validateOnly is true) or uploaded (when validateOnly is false)
          format: int32
          example: 42
          exampleSetFlag: true
          types:
          - integer
      exampleSetFlag: false
      types:
      - object
    TargetDefinitionDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the target (up to 20 digits). Use this value as targetId when uploading assignments.
          example: '7782342274025111111'
          exampleSetFlag: true
          types:
          - string
        name:
          type: string
          description: The display name of the target.
          example: ARR
          exampleSetFlag: true
          types:
          - string
        description:
          type: string
          description: (Optional) A description of the target.
          example: Annual Recurring Revenue
          exampleSetFlag: true
          types:
          - string
        type:
          type: string
          description: "Indicates whether the target is measured in a currency amount or a number of items, such as deals or calls. Possible values: \nCURRENCY for monetary targets such as revenue quota \nUNIT for count-based targets such as number of deals."
          example: CURRENCY
          exampleSetFlag: true
          types:
          - string
        unit:
          type: string
          description: The label used to display the target type, for example `USD` or `deals`
          example: USD
          exampleSetFlag: true
          types:
          - string
        hierarchyType:
          type: string
          description: "The hierarchy type used to structure assignments for this target. Possible values: \nTEAM for assignments to team members or team rollups \nTERRITORY for assignments to territory nodes\n"
          example: TEAM
          exampleSetFlag: true
          types:
          - string
        createdDateTime:
          type:
          - string
          - 'null'
          description: The date and time the target was created, in ISO-8601 format (e.g. `2018-02-18T08:00:00Z`). May not be available for older records.
          example: '2024-01-15T10:30:00Z'
          exampleSetFlag: true
          types:
          - string
      description: List of targets defined for the workspace
      exampleSetFlag: false
      types:
      - object
    TargetDefinitionsResponse:
      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
        targets:
          type: array
          description: List of targets defined for the workspace
          exampleSetFlag: false
          items:
            $ref: '#/components/schemas/TargetDefinitionDto'
            exampleSetFlag: false
          types:
          - array
      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
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)