openapi: 3.1.0
info:
  title: Gainsight CS Bulk Accounts People 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: People
  description: Manage person records
paths:
  /data/objects/Person:
    post:
      operationId: upsertPeople
      summary: Gainsight Upsert person records
      description: Insert or update person records in Gainsight. Supports up to 50 records per call with upsert behavior based on key fields.
      tags:
      - People
      parameters:
      - name: keys
        in: query
        required: true
        description: Comma-separated key fields for matching (e.g., Email)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - records
              properties:
                records:
                  type: array
                  maxItems: 50
                  items:
                    $ref: '#/components/schemas/PersonRecord'
      responses:
        '200':
          description: Records upserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data/objects/Person/search:
    post:
      operationId: searchPeople
      summary: Gainsight Search person records
      description: Search for person records using filter criteria. Returns up to 5000 records per call.
      tags:
      - People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/PersonRecord'
                      totalCount:
                        type: integer
                      count:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data/objects/Person/{recordId}:
    get:
      operationId: getPerson
      summary: Gainsight Get a person record
      description: Retrieve a specific person record by Gainsight ID.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Person record returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/PersonRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePerson
      summary: Gainsight Delete a person record
      description: Delete a person record by Gainsight ID.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Record deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/people:
    get:
      operationId: listPeople
      summary: Gainsight List people
      description: Retrieve a list of person records from Gainsight.
      tags:
      - People
      parameters:
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: List of people returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/Person'
                      totalCount:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    WriteResponse:
      type: object
      properties:
        result:
          type: boolean
        data:
          type: object
          properties:
            count:
              type: integer
            insertedCount:
              type: integer
            updatedCount:
              type: integer
            failedCount:
              type: integer
            failures:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                  errorMessage:
                    type: string
    ApiResponse:
      type: object
      properties:
        result:
          type: boolean
        errorCode:
          type: string
        errorDesc:
          type: string
        requestId:
          type: string
    Person:
      type: object
      properties:
        Gsid:
          type: string
          description: Gainsight unique identifier
        FirstName:
          type: string
          description: First name
        LastName:
          type: string
          description: Last name
        Email:
          type: string
          format: email
          description: Email address
        CompanyId:
          type: string
          description: Associated company ID
        Role:
          type: string
          description: Role or title
        Location:
          type: string
          description: Location
        CreatedDate:
          type: string
          format: date-time
          description: Record creation timestamp
        ModifiedDate:
          type: string
          format: date-time
          description: Record last modified timestamp
    SearchRequest:
      type: object
      properties:
        select:
          type: array
          items:
            type: string
        where:
          type: object
          properties:
            conditions:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  alias:
                    type: string
                  value: {}
                  operator:
                    type: string
                    enum:
                    - EQ
                    - NE
                    - GT
                    - GTE
                    - LT
                    - LTE
                    - CONTAINS
                    - STARTS_WITH
                    - ENDS_WITH
                    - IN
                    - NOT_IN
            expression:
              type: string
        orderBy:
          type: object
          properties:
            field:
              type: string
            order:
              type: string
              enum:
              - ASC
              - DESC
        limit:
          type: integer
          maximum: 5000
        offset:
          type: integer
    PersonRecord:
      type: object
      properties:
        Gsid:
          type: string
          description: Gainsight unique identifier
        FirstName:
          type: string
          description: First name
        LastName:
          type: string
          description: Last name
        Email:
          type: string
          format: email
          description: Email address
        CompanyId:
          type: string
          description: Associated company Gsid
        CompanyName:
          type: string
          description: Associated company name
        Title:
          type: string
          description: Job title
        Role:
          type: string
          description: Contact role
        Phone:
          type: string
          description: Phone number
        Location:
          type: string
          description: Location
        LinkedinUrl:
          type: string
          format: uri
          description: LinkedIn profile URL
        MasterAvatarTypeCode:
          type: string
          description: Avatar type code
        Timezone:
          type: string
          description: Timezone
        SfdcContactId:
          type: string
          description: Salesforce contact ID
        NPS:
          type: number
          description: Net promoter score
        IsPrimary:
          type: boolean
          description: Whether this is the primary contact
        IsActive:
          type: boolean
          description: Whether the person is active
        CreatedDate:
          type: string
          format: date-time
          description: Record creation timestamp
        ModifiedDate:
          type: string
          format: date-time
          description: Last modification timestamp
  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
  parameters:
    pageSize:
      name: pageSize
      in: query
      description: Number of records per page
      schema:
        type: integer
        default: 25
        maximum: 100
    pageNumber:
      name: pageNumber
      in: query
      description: Page number for pagination
      schema:
        type: integer
        default: 0
    recordId:
      name: recordId
      in: path
      required: true
      description: Gainsight record unique identifier (Gsid)
      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