openapi: 3.1.0
info:
  title: Gainsight CS Bulk Accounts 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: Accounts
  description: Manage account records and attributes
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: Gainsight List accounts
      description: Retrieve a paginated list of accounts in Gainsight PX.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/scrollId'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  scrollId:
                    type: string
                  totalHits:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccount
      summary: Gainsight Create or update an account
      description: Create a new account or update an existing account.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountInput'
      responses:
        '200':
          description: Account created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Gainsight Get an account
      description: Retrieve a specific account by ID.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Account details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAccount
      summary: Gainsight Update an account
      description: Update specific attributes of an account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountInput'
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAccount
      summary: Gainsight Delete an account
      description: Delete an account from Gainsight PX.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '204':
          description: Account deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: Unique account identifier
      schema:
        type: string
    filter:
      name: filter
      in: query
      description: Filter expression for results
      schema:
        type: string
    scrollId:
      name: scrollId
      in: query
      description: Scroll ID for cursor-based pagination
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page
      schema:
        type: integer
        default: 20
        maximum: 500
    sort:
      name: sort
      in: query
      description: Sort field and direction (e.g., lastSeenDate:desc)
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found
    BadRequest:
      description: Invalid request body or parameters
    Unauthorized:
      description: Authentication failed or API key is missing
  schemas:
    AccountInput:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique account identifier
        name:
          type: string
          description: Account name
        trackedSubscriptionId:
          type: string
          description: Tracked subscription ID
        sfdcId:
          type: string
          description: Salesforce account ID
        plan:
          type: string
          description: Account plan or tier
        customAttributes:
          type: object
          description: Custom account attributes
    Account:
      type: object
      properties:
        id:
          type: string
          description: Account unique identifier
        name:
          type: string
          description: Account name
        trackedSubscriptionId:
          type: string
          description: Tracked subscription ID
        sfdcId:
          type: string
          description: Salesforce account ID
        lastSeenDate:
          type: integer
          format: int64
          description: Last seen timestamp
        dupisBuyer:
          type: boolean
          description: Whether the account is a buyer
        numberOfUsers:
          type: integer
          description: Number of users in the account
        numberOfVisits:
          type: integer
          description: Total visits from the account
        plan:
          type: string
          description: Account plan or tier
        customAttributes:
          type: object
          description: Custom account attributes
  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