Gainsight Jobs API

openapi: 3.1.0
info:
  title: Gainsight CS Bulk Accounts Jobs API
  description: The Gainsight Bulk API is an asynchronous connector that automates insert or update of large data volumes from CSV files into Gainsight standard and custom objects, with rate limits of 10 calls per hour and 100 per day.
  version: '1.0'
  contact:
    name: Gainsight Support
    url: https://support.gainsight.com
    email: support@gainsight.com
  termsOfService: https://www.gainsight.com/terms-of-service/
servers:
- url: https://{domain}.gainsightcloud.com/v1
  description: Gainsight CS Production
  variables:
    domain:
      default: customer
      description: Customer-specific domain prefix
security:
- apiKey: []
tags:
- name: Jobs
  description: Manage bulk import jobs
paths:
  /bulk/jobs:
    post:
      operationId: createBulkJob
      summary: Gainsight Create a bulk job
      description: Create a new bulk import job to insert or update records from a CSV file into a Gainsight object. Rate limited to 10 calls per hour and 100 per day.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - objectName
              - operation
              - file
              properties:
                objectName:
                  type: string
                  description: Target Gainsight object name
                operation:
                  type: string
                  enum:
                  - INSERT
                  - UPDATE
                  - UPSERT
                  description: Bulk operation type
                keyFields:
                  type: string
                  description: Comma-separated key fields for matching (required for UPDATE and UPSERT)
                file:
                  type: string
                  format: binary
                  description: CSV file containing records to import
      responses:
        '200':
          description: Bulk job created
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/BulkJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: Rate limit exceeded
    get:
      operationId: listBulkJobs
      summary: Gainsight List bulk jobs
      description: Retrieve a list of bulk import jobs.
      tags:
      - Jobs
      parameters:
      - name: status
        in: query
        description: Filter by job status
        schema:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
      - name: limit
        in: query
        description: Maximum number of jobs to return
        schema:
          type: integer
          default: 25
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Jobs returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/BulkJob'
                      totalCount:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bulk/jobs/{jobId}:
    get:
      operationId: getBulkJob
      summary: Gainsight Get bulk job status
      description: Retrieve the status and details of a specific bulk job.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      responses:
        '200':
          description: Job details returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/BulkJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /bulk/jobs/{jobId}/errors:
    get:
      operationId: getBulkJobErrors
      summary: Gainsight Get bulk job errors
      description: Retrieve error details for a completed bulk job.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      responses:
        '200':
          description: Job errors returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BulkJobError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found
    BadRequest:
      description: Invalid request body or parameters
    Unauthorized:
      description: Authentication failed or access key is missing
  schemas:
    BulkJobError:
      type: object
      properties:
        rowNumber:
          type: integer
          description: Row number in the CSV file
        errorMessage:
          type: string
          description: Error message
        fieldName:
          type: string
          description: Field that caused the error
    BulkJob:
      type: object
      properties:
        jobId:
          type: string
          description: Bulk job unique identifier
        objectName:
          type: string
          description: Target object name
        operation:
          type: string
          enum:
          - INSERT
          - UPDATE
          - UPSERT
          description: Operation type
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          description: Job status
        totalRecords:
          type: integer
          description: Total records in the file
        processedRecords:
          type: integer
          description: Number of records processed
        successCount:
          type: integer
          description: Number of successful records
        failureCount:
          type: integer
          description: Number of failed records
        fileName:
          type: string
          description: Original CSV file name
        createdDate:
          type: string
          format: date-time
          description: Job creation timestamp
        completedDate:
          type: string
          format: date-time
          description: Job completion timestamp
  parameters:
    jobId:
      name: jobId
      in: path
      required: true
      description: Bulk job unique identifier
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      name: accessKey
      in: header
      description: Gainsight CS REST API access key
externalDocs:
  description: Bulk API Documentation
  url: https://support.gainsight.com/gainsight_nxt/API_and_Developer_Docs/Bulk_API/Gainsight_Bulk_REST_APIs