Skip to main content
Gainsight Inc.

Relationship APIs

This article provides details of REST APIs that can be used for viewing, creating, updating, and deleting records in the Relationship object.

Overview

Relationship provides the flexibility to accurately model and manage your complex customer structures by creating Relationship Types and Relationships. Relationships take Customer Success beyond managing Companies, they help CS manage each connection point (Relationship) with your customer.

The following are the APIs available to manage Relationships in Gainsight:

  • View Relationships
  • Create Relationships
  • Create Relationships using Lookups
  • Update Relationship Records
  • Upsert Relationship Records
  • Delete Relationships
  • Gainsight API Limits

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

  • Synchronous API Calls: 100 API calls per min / 50,000 API call per day
  • Asynchronous API Calls (Gainsight bulk APIs limit): 10 calls per hour / 100 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.

Pre-requisites

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 of 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.

View Relationships

This API can be used to view all the Relationships in your Gainsight instance.

Note: If you think there are more than 5000 records that can be fetched, pass another API call with Offset as 5001 so that remaining records (maximum 5000 records again) are fetched.

Method Details

API Details Description
Request Method POST
Request Endpoint

https://<customer domain>/v1/data/objects/query/relationship

Note: In the URL, replace the customer domain with your domain.

Header
  • 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>

Sample Request

{
    "limit": 100,
    "offset": 0,
    "select": [
        "Name",
        "Arr",
        "Mrr"
    ],
    "where": null,
    "orderBy": {
        "Name": "asc"
    }
}

Sample Success Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "5e3f7040-2a6d-42f2-bdf1-fe9e02faa665",
    "data": {
        "records": [
            {
                "Name": "Account10",
                "Arr": 200.0,
                "Mrr": null
            },
            {
                "Name": "Account100",
                "Arr": 200.0,
                "Mrr": null
            },
            {
                "Name": "Account1000",
                "Arr": 200.0,
                "Mrr": null
            },
            {
                "Name": "Account10000",
                "Arr": 200.0,
                "Mrr": null
            },
            {
                "Name": "Account1001",
                "Arr": 200.0,
                "Mrr": null
            }
       ]
    },
    "message": null
}

Sample Failure Response

{
    "result": false,
    "errorCode": "P_5005",
    "errorDesc": "Column t1.Name1 is either deleted or not exists Query :SELECT \"t1\".\"Name1\" AS \"Name1\",\"t1\".\"Arr\" AS \"Arr\",\"t1\".\"Mrr\" AS \"Mrr\" FROM \"company\" AS \"t1\" ORDER BY \"Name\" ASC LIMIT 100 OFFSET 0",
    "requestId": "1e8a7b66-511f-4bdf-9f4c-5ef43518fd63",
    "data": null,
    "message": null
}

Create Relationship(s)

This API can be used to create Relationships in Gainsight using Company Id and Type Id.

Note: Relationship Name, Type ID, Company ID are the mandatory fields for creating a Relationship.

Method Details

API Details Description
Request Method POST
Request Endpoint

https://<customer domain>/v1/data/objects/relationship

Note: In the URL, replace the customer domain with your domain.

Header
  • 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>

Sample Request

{
   "records": [
       {
           "Name": "Iphones",
           "Arr": "40000000000",
           "Mrr": "50000000",
           "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
           "TypeId":"1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02",
           "Stage":"1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR"
       },
       {
           "Name": "Ipads",
           "Arr": "5600000000",
           "Mrr": "450000000",
           "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
            "TypeId":"1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02",
           "Status":"1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R"
       },
       {
           "Name": "IWatch",
           "Arr": "5600000000",
           "Mrr": "4300000",
           "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
           "TypeId":"1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02",
           "Status":"1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R"
       }
   ]
}

Sample Success Response

{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "requestId": "6fc8356b-1176-4de2-adea-bf1ebef4db1a",
   "data": {
       "count": 2,
       "errors": [],
       "records": [
           {
               "Arr": 5600000000.00000,
               "Comments": null,
               "Company_Name__gc": null,
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T09:37:02Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSUXOIW4VTSV300OS5H97",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T09:37:02Z",
               "Mrr": 450000000.00000,
               "Name": "Ipads",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": null,
               "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R",
               "Trend": null,
               "Type_Name__gc": null,
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           },
            {
               "Arr": 40000000000.00000,
               "Comments": null,
               "Company_Name__gc": null,
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T09:37:02Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSUQEVP2PR6XSLWPBIVRK",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T09:37:02Z",
               "Mrr": 50000000.00000,
               "Name": "Iphones",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR",
               "Status": null,
               "Trend": null,
               "Type_Name__gc": null,
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           }
       ]
   },
   "message": null
}

Sample Failure Response

{
    "result": false,
    "errorCode": "GSOBJ_1012",
    "errorDesc": "Invalid/Inactive value provided for picklist. (Stage = 123444).",
    "requestId": "41946de2-0faa-4944-96ec-8e75e46d179a",
    "data": {
        "count": 0,
        "errors": [
            [
                {
                    "success": false,
                    "oldValue": "123444",
                    "parsedValue": "123444",
                    "errors": [
                        {
                            "errorMessage": "Invalid/Inactive value provided for picklist.",
                            "errorCode": "GSOBJ_1012",
                            "fieldName": "Stage",
                            "invalidValue": [
                                "123444"
                            ]
                        }
                    ]
                }
            ]
        ],
        "records": null
    },
    "message": null
}

Create Relationship(s) using Lookups

Method Details

API Details Description
Request Method POST
Request Endpoint

https://<customer domain>/v1/data/objects/relationship

Note: In the URL, replace the customer domain with your domain.

Header
  • 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>

Sample Request

{
   "records": [
       {
           "Name": "Iphones",
           "Arr": "40000000000",
           "Mrr": "50000000",
           "Company_Name__gc": "Apple",
           "Type_Name__gc": "Demo Relationship",
           "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR"
       },
       {
           "Name": "Ipads",
           "Arr": "5600000000",
           "Mrr": "450000000",
           "Company_Name__gc": "Apple",
           "Type_Name__gc": "Demo Relationship",
           "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R"
       },
       {
           "Name": "IWatch",
           "Arr": "5600000000",
           "Mrr": "4300000",
           "Company_Name__gc": "Apple",
           "Type_Name__gc": "Demo Relationship",
           "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R"
       }
   ],
   "lookups": {
       "CompanyId": {
           "isLookup": true,
           "fields": {
               "Company_Name__gc": "Name"
           },
           "objectName": "company",
           "onNoMatch": "ERROR",
           "multiMatchOption": "FIRSTMATCH",
           "lookupField": "Gsid"
       },
       "TypeId": {
           "isLookup": true,
           "fields": {
               "Type_Name__gc": "Name"
           },
           "objectName": "relationship_type",
           "onNoMatch": "ERROR",
           "multiMatchOption": "FIRSTMATCH",
           "lookupField": "Gsid"
       }
   }
}

Sample Success Response

{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "requestId": "6fc8356b-1176-4de2-adea-bf1ebef4db1a",
   "data": {
       "count": 2,
       "errors": [],
       "records": [
           {
               "Arr": 5600000000.00000,
               "Comments": null,
               "Company_Name__gc": null,
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T09:37:02Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSUXOIW4VTSV300OS5H97",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T09:37:02Z",
               "Mrr": 450000000.00000,
               "Name": "Ipads",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": null,
               "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R",
               "Trend": null,
               "Type_Name__gc": null,
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           },
            {
               "Arr": 40000000000.00000,
               "Comments": null,
               "Company_Name__gc": null,
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T09:37:02Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSUQEVP2PR6XSLWPBIVRK",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T09:37:02Z",
               "Mrr": 50000000.00000,
               "Name": "Iphones",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR",
               "Status": null,
               "Trend": null,
               "Type_Name__gc": null,
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           }
       ]
   },
   "message": null
}

Sample Failure Response

Case 1: The following error message appears when company Id and TypeId are not found while creating a Relationship.

{
   "result": false,
   "errorCode": "GSOBJ_1008",
   "errorDesc": null,
   "requestId": "76e92d82-b2ff-48f5-b701-2954dc6d55f3",
   "data": null,
   "message": "No CompanyId resolved for lookup information. Criteria: Company_Name__gc = Apple1 "
}

Case 2: The following error message appears when mandatory fields(Relationship Name, Type ID, Company ID) are missing in the request:

{
   "result": false,
   "errorCode": "GSOBJ_1025",
   "errorDesc": "Data for required columns is absent, please re-check your data.",
   "requestId": "22a451b7-a90a-4a6d-943d-b4311408f0d4",
   "data": null,
   "message": "Required columns are absent. [Name]"
}

Update Relationship Record(s)

This API can be used for updating the Relationship fields by using identifiers.

Method Details

API Details Description
Request Method PUT
Request Endpoint

https://<customer domain>/v1/data/objects/relationship?keys=<Identifier>

Note: In the URL, replace the customer domain and identifier with your domain and the identifier field name.

Header
  • 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>

Sample Request

{
  "records": [
      {
          "Name": "Iphones",
          "Arr": "78900888098",
          "Mrr": "45789909090",
          "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR"
      }
  ]
}

Sample Success Response

{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "requestId": "32d8232b-c900-4e1f-8b9b-23980334a921",
   "data": {
       "count": 1,
       "errors": [],
       "records": [
           {
               "Arr": 78900888098.00000,
               "Comments": null,
               "Company_Name__gc": "Apple",
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T10:58:05Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSU9VIJASIQ3DDAN11LQU",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T10:58:51Z",
               "Mrr": 45789909090.00000,
               "Name": "Iphones",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR",
               "Status": null,
               "Trend": null,
               "Type_Name__gc": "Demo Relationship",
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02",
               "X-GS-MSGID": null
           }
       ]
   },
   "message": null
}

Sample Failure Response

The following error message is displayed when no entity matches with the given key as identifier while updating the Relationship fields.

{
   "result": false,
   "errorCode": "GSOBJ_1011",
   "errorDesc": "No entity matches the given criteria, please re-check your request.",
   "requestId": "6952e632-de4a-4c6b-88c8-819b7b52591b",
   "data": null,
   "message": "Failed to find record for given criteria."
}

Upsert Relationship Record(s)

This API can be used to find the Relationship (using Identifier) and update it. If the Relationship is not found it will create a Relationship.

Method Details

API Details Description
Request Method PUT
Request Endpoint

https://<customer domain>/v1/data/objects/relationship/upsert?keys=Name

Note: In the URL, replace the customer domain and name with your domain and the required field name.

Header
  • 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>

Sample Request

{
   "records": [
       {
           "Name": "Iphones",
           "Arr": "500",
           "Mrr": "4000",
           "Company_Name__gc": "Apple",
           "Type_Name__gc": "Demo Relationship",
           "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR"
       },
       {
           "Name": "Macbooks",
           "Arr": "600000",
           "Mrr": "750000",
           "Company_Name__gc": "Apple",
           "Type_Name__gc": "Demo Relationship",
           "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R"
       }
   ],
   "lookups": {
       "CompanyId": {
           "isLookup": true,
           "fields": {
               "Company_Name__gc": "Name"
           },
           "objectName": "company",
           "onNoMatch": "ERROR",
           "multiMatchOption": "FIRSTMATCH",
           "lookupField": "Gsid"
       },
       "TypeId": {
           "isLookup": true,
           "fields": {
               "Type_Name__gc": "Name"
           },
           "objectName": "relationship_type",
           "onNoMatch": "ERROR",
           "multiMatchOption": "FIRSTMATCH",
           "lookupField": "Gsid"
       }
   }
}

Sample Success Response

{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "requestId": "ea3984ad-9988-435a-bdd8-cb3fc3b26cf5",
   "data": {
       "count": 2,
       "errors": [],
       "records": [
           {
               "Arr": 500.00000,
               "Comments": null,
               "Company_Name__gc": "Apple",
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T11:08:33Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSU9VIJASIQ3DDAN11LQU",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T11:08:33Z",
               "Mrr": 4000.00000,
               "Name": "Iphones",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": "1I0054U9FAKXZ0H26HKBJJA7U0VR6BMDZJRR",
               "Status": null,
               "Trend": null,
               "Type_Name__gc": "Demo Relationship",
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           },
           {
               "Arr": 600000.00000,
               "Comments": null,
               "Company_Name__gc": "Apple",
               "CompanyId": "1P02FBB5AFNYP50D8Z8DS12QHN7FOPFBR9QU",
               "CreatedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "CreatedDate": "2022-06-23T11:08:33Z",
               "Csat": null,
               "Csm": null,
               "CurrentScore": null,
               "Gsid": "1P05C491NYX7EN2GSU71HPFUJFRVYHTXYQ73",
               "LifetimeInMonths": null,
               "ModifiedBy": "1P01C0SC8BPJ2OVKDCJS330DEMQ9MZ8FC87H",
               "ModifiedDate": "2022-06-23T11:08:33Z",
               "Mrr": 750000.00000,
               "Name": "Macbooks",
               "Nps": null,
               "OnetimeRevenue": null,
               "OriginalContractDate": null,
               "OverallScoreComments": null,
               "PreviousScore": null,
               "ScorecardId": null,
               "SfdcRelationshipId": null,
               "Stage": null,
               "Status": "1I0054U9FAKXZ0H26HRLAQ0HW7G720Q2UU8R",
               "Trend": null,
               "Type_Name__gc": "Demo Relationship",
               "TypeId": "1P06ACH2YVJSBHBRPMX48OG68BE1RSH6BB02"
           }
       ]
   },
   "message": null
}

Sample Failure Response

The following error message is displayed when mandatory fields are missing in the request.

{
   "result": false,
   "errorCode": "GSOBJ_1025",
   "errorDesc": "Data for required columns is absent, please re-check your data.",
   "requestId": "ea8e45aa-74e0-4945-b680-4485ecdc3fe7",
   "data": null,
   "message": "Required columns are absent. [Name]"
}

Delete Relationship(s)

This API can be used to delete a Relationship using GSID.

Method Details

API Details Description
Request Method DELETE
Request Endpoint

https://<customer domain>/v1/data/objects/relationship/{GSID}

Note: In the URL, replace the customer domain and GSID with your domain and the GSID of the Relationship.

Header
  • 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>

Sample Request

{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "requestId": "51753a3c-b78a-433e-93ad-c77d3921ec46",
   "data": "Delete process initiated for 1 records.",
   "message": null
}

Error Code(s)

For information about the error codes for the Relationship APIs, refer to the Error Codes for Company, Relationship, and Custom Object APIs article.

  • Was this article helpful?