The Gainsight REST API allows developers to integrate customer success data, automate workflows, and build custom applications on top of the Gainsight platform.
openapi: 3.1.0
info:
title: Gainsight REST API
description: >-
The Gainsight REST API allows developers to integrate customer success data,
automate workflows, and build custom applications on top of the Gainsight
platform. Provides access to core Gainsight objects and operations.
version: '1.0'
contact:
name: Gainsight Support
url: https://support.gainsight.com
email: support@gainsight.com
termsOfService: https://www.gainsight.com/terms-of-service/
externalDocs:
description: Gainsight API Documentation
url: https://support.gainsight.com/PX/API_for_Developers
servers:
- url: https://api.gainsight.com
description: Gainsight Production API
tags:
- name: Companies
description: Manage company records
- name: People
description: Manage person records
- name: Reports
description: Run reports and retrieve analytics data
security:
- apiKey: []
paths:
/v1/companies:
get:
operationId: listCompanies
summary: Gainsight List companies
description: Retrieve a list of company records from Gainsight.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/pageNumber'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
description: List of companies returned successfully
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/Company'
totalCount:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCompany
summary: Gainsight Create a company
description: Create a new company record in Gainsight.
tags:
- Companies
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyInput'
responses:
'200':
description: Company created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/companies/{companyId}:
get:
operationId: getCompany
summary: Gainsight Get a company
description: Retrieve a specific company record by ID.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/companyId'
responses:
'200':
description: Company details returned
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
$ref: '#/components/schemas/Company'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCompany
summary: Gainsight Update a company
description: Update an existing company record.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyInput'
responses:
'200':
description: Company updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCompany
summary: Gainsight Delete a company
description: Delete a company record by ID.
tags:
- Companies
parameters:
- $ref: '#/components/parameters/companyId'
responses:
'200':
description: Company 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'
/v1/reports:
post:
operationId: runReport
summary: Gainsight Run a report
description: Execute a report query against Gainsight data.
tags:
- Reports
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reportId:
type: string
description: ID of the report to execute
filters:
type: object
description: Optional filters to apply
responses:
'200':
description: Report data returned
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: object
properties:
records:
type: array
items:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
apiKey:
type: apiKey
name: accessKey
in: header
description: Gainsight REST API access key
parameters:
companyId:
name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
pageNumber:
name: pageNumber
in: query
description: Page number for pagination
schema:
type: integer
default: 0
pageSize:
name: pageSize
in: query
description: Number of records per page
schema:
type: integer
default: 25
maximum: 100
responses:
Unauthorized:
description: Authentication failed or access key is missing
BadRequest:
description: Invalid request body or parameters
NotFound:
description: The requested resource was not found
schemas:
ApiResponse:
type: object
properties:
result:
type: boolean
description: Whether the operation was successful
errorCode:
type: string
description: Error code if the operation failed
errorDesc:
type: string
description: Error description if the operation failed
requestId:
type: string
description: Unique ID for the request
Company:
type: object
properties:
Gsid:
type: string
description: Gainsight unique identifier
Name:
type: string
description: Company name
Industry:
type: string
description: Industry classification
ARR:
type: number
description: Annual recurring revenue
LifecycleStage:
type: string
description: Current lifecycle stage
Status:
type: string
description: Company status
CSMName:
type: string
description: Customer success manager name
Employees:
type: integer
description: Number of employees
OriginalContractDate:
type: string
format: date
description: Original contract start date
RenewalDate:
type: string
format: date
description: Next renewal date
CreatedDate:
type: string
format: date-time
description: Record creation timestamp
ModifiedDate:
type: string
format: date-time
description: Record last modified timestamp
CompanyInput:
type: object
required:
- Name
properties:
Name:
type: string
description: Company name
Industry:
type: string
description: Industry classification
ARR:
type: number
description: Annual recurring revenue
LifecycleStage:
type: string
description: Current lifecycle stage
Status:
type: string
description: Company status
Employees:
type: integer
description: Number of employees
RenewalDate:
type: string
format: date
description: Next renewal date
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