API for Company Team Record

Introduction

Admins can use Company Teams REST external APIs to delete, bulk delete, upsert, and fetch company teams records.

Prerequisite: To use these APIs, ensure that the company team is enabled for your tenant. Failure to do so can result in an exception/error.

Authentication

To use these User Management APIs, ensure that you generate Access Token:

API Authentication: API access is controlled using a unique Access Key. Contact your Gainsight Admin to get an access key for the Gainsight tenant to which you want to send REST API requests. For more information on how to generate or share an access key, refer to the Generate API Access Key article.

Once you get the access key, you must pass the access key as part of the request header accesskey for all of your API requests into Gainsight. The Access Key does not expire.

Headers

Key	Value
content-type	application/json
accept	application/json, text/plain, /
accept-language	en-GB,en-US;q=0.9,en;q=0.8
<authentication>	<Access Key>

Throttling Limits

The following are the overall recommended API limits in Gainsight (The exact limits can vary based on your package):

Synchronous API Calls: 100 API calls per min / 50,000 API call per day

API	Rate Limit
External User Management APIs	100 requests per hour / 1000 requests per day

Note: All of the above API limits are *Fixed window rate limits.* Fixed window rate limiting restricts the number of API requests at a specific time. For example, a server can have a rate limiting component that implements a fixed window algorithm that only accepts 100 requests per minute. The time-frame is fixed, and it starts at a specific time. For example, the server will only serve 100 requests between 10:00 am, and 10:01 am.

Delete Company Teams Records

The Delete REST API of the Company Teams record allows the deletion of company team records within Gainsight. Many Gainsight customers use external applications, such as Microsoft Dynamics, to manage account teams, and synchronize this information with the company teams object in Gainsight. The Delete API helps automate the deletion of company team records in Gainsight whenever a corresponding record is deleted in source systems such as Microsoft Dynamics.

Method

DELETE

Endpoint URL

v1/teams/services/companyTeam/{gsid}

Parameters

Parameter

(*Mandatory)

Data Type

Description

GSID*

String

A String value that contains the GSID of a company team record.

Sample Success Response


{ 
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": "Record with GSID: 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ successfully deleted.",
}

Sample Failure Response


{  
  "result": false,
  "errorCode": "GSOBJ_1XXX",
  "errorDesc": "No data found for given criteria",
  "requestId": "58222b97-eaf0-402e-854d-1914987c4b49",
  "data": null,
}

Bulk Delete Company Teams Records

The Bulk Delete REST API of the Company Teams record allows the deletion of company team records in bulk within Gainsight. Many Gainsight customers use external applications, such as Microsoft Dynamics, to manage account teams and synchronize this information with the company teams object in Gainsight. The Bulk Delete API helps automate the deletion of company team records in Gainsight whenever corresponding records are deleted in source systems such as Microsoft Dynamics.

Method

POST

Endpoint URL

v1/teams/services/companyTeam/delete

Sample Request Body

 
"1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
"1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A",
"1P01936XHTA4SF76ZUW5J2RVEZZ8H33C8MAM"]

Parameters

Parameter

(*Mandatory)

Data Type

Description

List of company Team GSID*

List of String

A list of String value that contains the list of GSID of a company team record to be deleted in bulk.

Sample Success Response


{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": {
    "success": {
      "gsid": [
        "1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
        "1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A"
      ]
    },
    "errors": [
      {
        "gsid": [
          "1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
          "1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A"
          
   ],
        "errorCode": "GSOBJ_1XXX",
        "errorDesc": "No data found for given criteria"
      }
    ]
  }
}

Sample Failure Response


{
    "result": false,
    "errorCode": "GU_1129",
    "errorDesc": "Invalid GSID value.",
    "localizedErrorDesc": "Invalid GSID value.",
    "requestId": "a0f958fb-fee7-4a15-8029-e334350ce1b7",
    "data": null,
    "message": null,
    "localizedMessage": null
}

Upsert Company Teams Records

The Upsert API serves a dual purpose. It enables the insertion of new company team records and updates existing ones in Gainsight.

Method

PUT

Endpoint URL

v1/teams/services/companyTeam?key=CompanyGsid,UserGsid 
or 
v1/teams/services/companyTeam?key=Gsid

IMPORTANT:

Key Options:
- The key parameter can be either Gsid (key=Gsid) or a combination of CompanyGsid and UserGsid (key=CompanyGsid,UserGsid).
Required Fields:
- If Gsid is provided as the identifier (key=Gsid), it is mandatory to include the Gsid field in the request body.
- If CompanyGsid and UserGsid are provided as the identifiers (key=CompanyGsid,UserGsid), it is mandatory to include CompanyGsid and UserGsid in the request body.
Default Identifier:
- If no key parameter is provided in the endpoint URL, CompanyGsid and UserGsid are taken as the default identifiers. Therefore, if no key is passed in the endpoint URL, it is mandatory to provide the CompanyGsid and UserGsid fields in the request body.

Sample Request Body

The following is a sample request body with CompanyName and UserName in the Request Body.

 

{
    "records": [
        {
            "UserRole" : "Account Manager",
            "CompanyName": "IBM",
            "UserName": "Sandeep Kumar", 
            "TeamAdmin" : "true",
            "Custom_String1__gc" : "hello",
            "Custom_Picklist__gc" : "Account Manager",
        },
        {
            "UserRole" : "Account Manager",
            "CompanyName": "Youtube",
            "UserName": "Sandeep Kumar",
            "TeamAdmin" : "true",
            "Custom_String__gc" : "hello",
            "Custom_Picklist__gc" : "Account Manager"
        }
    ],
      "lookups": {
        "CompanyGsid": {
            "fields": {
                "CompanyName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "Company",
            "multiMatchOption": "FIRSTMATCH"
        },
        "UserGsid": {
            "fields": {
                "UserName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "GsUser"
        }
    }
      
}

The following is a sample request body with CompanyGsid and UserGsid in the Request Body.

 
{
    "records": [
        {
            "UserRole" : "Account Manager",
            "CompanyName": "IBM",
            "UserName": "Sandeep Kumar", 
            "TeamAdmin" : "true",
            "Custom_String1__gc" : "hello",
            "Custom_Picklist__gc" : "Account Manager",
        },
        {
            "UserRole" : "Account Manager",
            "CompanyName": "Youtube",
            "UserName": "Sandeep Kumar",
            "TeamAdmin" : "true",
            "Custom_String__gc" : "hello",
            "Custom_Picklist__gc" : "Account Manager"
        }
    ],
      "lookups": {
        "CompanyGsid": {
            "fields": {
                "CompanyGsid": "Gsid"
            },
            "lookupField": "Gsid",
            "objectName": "Company",
            "multiMatchOption": "FIRSTMATCH"
        },
        "UserGsid": {
            "fields": {
                "UserGsid": "Gsid"
            },
            "lookupField": "Gsid",
            "objectName": "GsUser"
        }
    }  
     
}

Parameters

The following are the list of parameters when key = CompanyGsid, UserGsid.

Parameter (*Mandatory)	Data Type	Description
CompanyGsid* or CompanyName *	String	A String value that contains the GSID of a company record. A String value that contains the name of the company.
UserGsid* or UserName*	String	A String value that contains the GSID of the user. A String value that contains the name of the user.
UserRole	String	A String value that contains the role of the user in the company team record. Note: When inserting a new record, if the UserRole field is not provided in the request body, its default value is set to Account Manager.
TeamAdmin	Boolean	A Boolean value indicating whether the user is an administrator of the company team or not. Note: When inserting a new record, if the TeamAdmin field is not provided in the request body, its default value is set to False.
ObjectName	String	A String value that contains the lookup object name.
multiMatchOption FIRSTMATCH MARKASERROR	String	A String value that contains the GSID of the first match between the lookup JSON and the lookup object. A String value that contains an error when multiple records match the criteria between JSON and the Lookup object.
onNoMatch NULLABLE DEFAULTVALUE ERROR	String	(Default) A String value that inserts null value into the target field when no match is found. A String value that inserts default value into the target field. A String value that contains an error when no records match the criteria between JSON and the Lookup object.

The following are the list of parameters when key = Gsid.

Parameter

(*Mandatory)

Data Type

Description

Gsid*

String

A String value that contains the GSID of the company team record.

UserRole

String

A String value that contains the role of the user in the company team record.
Note: When inserting a new record, if the UserRole field is not provided in the request body, its default value is set to Account Manager.

TeamAdmin

Boolean

A Boolean value that indicates whether the user is an administrator of the company team or not.
Note: When inserting a new record, if the TeamAdmin field is not provided in the request body, its default value is set to False.

Sample Success Response


{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "6672f3fd-f049-4434-8a4b-46a1b7b09308",
    "data": {
        "success": {
            "records": [
                {
                    "UserGsid": "1P01A7JNOWRLONI81IADNSU9OSAE8VW22OGV",
                    "Custom_Picklist__gc": "Account Manager",
                    "CompanyGsid": "1P02EWJH7V1ARTU135948UTCK78QC96QL78G",
                    "CreatedBy": "123",
                    "UserRole": "Account Manager",
                    "TeamAdmin": "true",
                    "Custom_String1__gc": "hello",
                    "ModifiedBy": "Sandeep Kumar"
                },
                {
                 {
                      "UserRole" : "Account Manager",
                      "CompanyGsid": "1P02EWJH7V1ARTU135948UTCK78QC96ABCWE",
                      "UserGsid": "1P01A7JNOWRLONI81IADNSU9OSAE8VW22OGV",
                      "TeamAdmin" : "true",
                      "Custom_String__gc" : "hello",
                     "Custom_Picklist__gc" : "Account Manager"
                }
            ]
        },
        "errors": null
    },
    "message": null,
    "localizedMessage": null
}

Sample Failure Response


{
"result": false,
"errorCode": "GU_2403",
"errorDesc": "Lookup objects [Company1] are not valid",
"requestId": "0bf61426-63ad-4774-ad95-4bd2f6c43c25",
"data": null,
"message": null
}

Fetch Company Teams Records

The Fetch API allows to retrieve specific details of company teams stored in Gainsight.

Method

POST

Endpoint URL

v1/teams/services/companyTeam/list

Sample Request Body

{
    "limit": 25,
    "page": 0,
    "orderBy": {
        "ModifiedDate": "desc"
    },
    "select": [
        "Gsid",
        "CompanyName",
        "UserName",
        "UserRole",
        "ModifiedDate"
    ],
    "where": {
        "conditions": [
            {
                "name": "CompanyName",
                "alias": "companyNotIn",
                "value": [
                    "Youtube"
                ],
                "operator": "NOT_IN"
            },
            {
                "alias": "companyIn",
                "name": "CompanyName",
                "operator": "IN",
                "value": [
                    "IBM"
                ]
            }
        ],
        "expression": "companyNotIn AND (companyIn)"
    }}

Parameters

Parameter (*Mandatory)	Data Type	Description
limit	Number	A Number value that contains a maximum number of records sent in one API call.
page	Number	A Number value that contains the next set of records based on the limit.
orderBy	Map	A Map value that contains a field name order by ascending or descending order.
select*	List of fields	A List to fetch the fields from an object.
where	Map	A Map value that is used to filter records and extract only those records that fulfil a specified condition.
Conditions	List	A List of conditions used to filter out the company team records.
expression	String	A String value that contains AND/OR operation.

Sample Success Response


{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "b518fb98-336d-404f-83ab-40fb01730867",
    "data": {
        "page": 0,
        "size": 1,
        "limit": 25,
        "records": [
            {
                "Gsid": "1P071TST1Z6DTGBG44KDYJG9KBNTDQMQ3QHO",
                "UserRole": "Pre-Sales Consultant",
                "ModifiedDate": "2023-10-03T10:03:32Z",
                "Name": "Admin User",
                "CompanyName": "IBM"
            }
        ]
    },
    "message": null,
    "localizedMessage": null
}

Sample Failure Response


{
    "result": false,
    "errorCode": "GU_1707",
    "errorDesc": "Failed to fetch records.",
    "localizedErrorDesc": "Failed to fetch records.",
    "requestId": "667951ba-b04f-4407-b326-1347645efdc6",
    "data": null,
    "message": null,
    "localizedMessage": null
}

Error Codes

Error Code	Error Message	Reason	HTTP Status Code
GU_8002	At least one GSID should be provided	When no GSID is passed in bulk delete.	400
GU_8003	No data found for the given criteria	When the given GSID in bulk delete is either already deleted or not present in the company record.	400
GU_8004	Request exceeds maximum allowed limit of: 50 records to delete records	When the given request in bulk delete contains more than 50 records.	416
GU_8005	Company team is currently not enabled	When the company team feature toggle is not enabled in delete or bulk delete.	400
GU_2400	Too many requests, Request limit reached	When the rate limit is exceeded in delete or bulk delete.	429
GU_1129	Invalid GSID value	When GSID is invalid in delete or bulk delete.	400
GU_3014	Lookups should not be null or empty if CompanyGsid/CompanyName or UserGsid/UserName are passed in request body	When the CompanyGsid/ CompanyName/ UserGsid/ UserName fields are included in the request body without passing the required lookup information.	400
GU_3017	Gsid is invalid	When GSID is not valid.	NA
GU_3018	Identifier {} should not be null or empty	When the identifier is not valid.	NA
GU_3019	Passed key : {} is not allowed, allowed keys are : Gsid or CompanyGsid,UserGsid	When identifiers are unrecognizable.	400
GU_3006	{} should not be null or empty.	When the request payload is empty.	400
GU_3016	Company Team Upsert Operation Failed	When the upsert company team request is failed.	NA
GU_3014	{} should not be null or empty if CompanyGsid/CompanyName or UserGsid/UserName are passed in request body	When the request lookup is empty.	NA
GU_8006	Request exceeds maximum allowed limit of: {} records to upsert records	When the limit for company teams upsert records exceeds.	416