Skip to main content
Gainsight Inc.

SCIM API

  1. Last updated
  2. Save as PDF
This article helps admins understand how the SCIM API automates user provisioning and de-provisioning by syncing roles and statuses in real time between your identity provider and Gainsight, eliminating manual user management.

This article helps admins understand how the SCIM API automates user provisioning and de-provisioning by syncing roles and statuses in real time between your identity provider and Gainsight, eliminating manual user management.

Overview

SCIM (System for Cross-domain Identity Management) APIs simplify user provisioning and de-provisioning for enterprise customers. By integrating with central identity management systems, admins can now automatically provision users through SCIM APIs, removing the need for manual user creation within each application. It ensures that critical user attributes, such as roles and statuses, are synced seamlessly between the IdP and Gainsight in real-time.

Key Benefits

  • Automated User Creation: SCIM APIs enable automatic user creation in Gainsight through integration with Identity Providers.
  • Seamless User Sync: User attributes, such as roles and statuses, are synced in real time between the IdP and Gainsight.
  • API-Driven User Management: Admins can manage users entirely through SCIM APIs, without the need to access the Gainsight UI.

API Scopes

  • GET APIs: Available for both super admins and non-super admins.
  • Create, Update, and Patch APIs: Available only to super admins.

SCIM Base URL: https://<<tenant-url>>/v1/users/services/scim

Authentication Mechanisms for SCIM APIs

Two authentication methods are supported to securely access SCIM APIs in Gainsight: M2M and OAuth.

Machine-to-Machine OAuth (M2M)

M2M OAuth allows server-to-server API authentication using a client ID and client secret, with no user interaction required. This method is ideal for backend systems like Azure that support client credentials flow.

For more information on M2M OAuth, refer to the Generate REST API Key article.

OAuth

OAuth is an authorization framework that enables user-delegated access via access tokens. This is suitable when applications need to access Gainsight APIs on behalf of an end-user or application.

For more information on OAuth, refer to the OAuth for Gainsight APIs article.

Throttling Limits

The following are the overall recommended API limits in Gainsight:

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

Get Access Token API

The Get Access Token API is used to generate an access token that is required to authenticate and authorize API requests.  For more information, click here.

Headers

Key Value
Authorization Basic base64(client_id:client_secret)

Method

POST

Endpoint URL

https://<<tenant-url>>/v1/users/m2m/oauth/token

Sample Success Response

{
      "access_token": "<<access_token value>>",
      "token_type": "Bearer",
      "expires_in": 86400
  }

Active State of a Token API

The Active state of a Token API is used to determine the active state of a token and meta-information about it, such as its expiry information. For more information, click here.

Headers

Key Value
Authorization Basic base64(client_id:client_secret)
Content-Type application/json

Method

POST

Endpoint URL

https://<<tenant-url>>/v1/users/m2m/oauth/token/introspect

Sample Request Body

{
      "access_token": "XXXXXXXXX"
}

Sample Success Response

{
  "active": true,
  "client_id": "XXXXXX",
  "token_type": "Bearer",
  "exp": 1729123263000
}

Sample Failure Response

{
"requestId": "170a3a0b-bfe4-4337-a961-a24196925d8b",
"error": "unauthorized"
}

SCIM Create User API

The SCIM Create User API automatically creates a new user in a system by integrating with external identity providers, ensuring streamlined user provisioning. In groups value and display both attributes are not mandatory, providing either one is acceptable.  

To add custom user attributes, ensure that all custom fields are included under the urn:ietf:params:scim:schemas:extension:gainsight:2.0:User namespace, as illustrated in the request payload below.

For IsSuperAdmin attribute can have true or false boolean value and LicenseType can have any of these Full, Viewer_Analytics, Viewer, Internal_Collaborator values.

Please note that custom user attribute mappings must be pre-configured in Gainsight as part of the SCIM setup before they can be used in any of the User APIs. Kindly contact the Gainsight Support team to configure this mapping.

Key Values
Authorization  Bearer {access_token}
Content-Type application/scim+json

 

IMPORTANT: For all the SCIM API requests, use this header for Authorization and Content-Type.

Method

POST

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users

Sample Request Body


{
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
       "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User"
  ],
  "userName": "sample1234",
  "name": {
      "givenName": "John",
      "familyName": "Dee"
  },
  "displayName": "John Dee",
  "emails": [
      {
          "primary": true,
          "value": "john@sample.com"
      }
  ],
   "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71",
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ], 
            "title": "Er",
  "active": true,
  "locale":"",
  "timezone":"",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "manager": {
          "value": "1P01A7JNOWRLONI81IT5J6FZYM2IMLB72ZVL",
          "displayName": "Andy"
      }
  }, 
  "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User": {
        "IsSuperAdmin": false,
        "custom_roles": [
            "JO Admin",
            "CSM"
        ],
        "LicenseType": "Full"    }
}

Sample Success Response

{
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU",
  "userName": "sample1234",
  "name": {
      "familyName": "Dee",
      "givenName": "John"
  },
  "displayName": "John Dee",
  "title": "Er",
  "timezone": "Asia/Kathmandu",
  "active": true,
  "emails": [
      {
          "value": "john@sample.com",
          "primary": true
      }
  ],
  "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71", 
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ],
  "roles": [
                {
                    "value": "Data Team"
                },
                {
                    "value": "JO Admin"
                }
            ],
  "meta": {
      "resourceType": "User",
      "created": "2024-10-10T23:49:13Z",
      "lastModified": "2024-10-10T23:49:13Z",
      "location": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "manager": {
          "value": "1P01A7JNOWRLONI81IT5J6FZYM2IMLB72ZVL"
      }
  }, 
   "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User": {
        "IsSuperAdmin": false,
        "custom_roles": [
            "JO Admin",
            "CSM"
        ],
        "LicenseType": "Full"    }
}

SCIM Update User API

The SCIM Update User API is used to modify existing user details, such as attributes or groups, by synchronizing updates from external identity providers. In groups value and display attributes are not mandatory, providing either one is acceptable.

Roles and Groups should always be included in the payload when updating. If these attributes are omitted, the system will not interpret them as empty.

To update custom user attributes, ensure that all custom fields are included under the urn:ietf:params:scim:schemas:extension:gainsight:2.0:User namespace, as illustrated in the request payload below, Custom attributes that are omitted in the payload will be treated as empty by the system. 

Method

PUT

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "sample1234",
  "id": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU",
  "name": {
      "givenName": "JohnDeer",
      "familyName": "Dee"
  },
  "displayName": "JohnDeer Dee",
  "emails": [
      {
          "primary": true,
          "value": "john@sample.com"
      }
  ],
   "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71",
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ],
   "title": "Er",
  "active": true,
  "locale":"de_DE",
  "timezone":"Europe/Berlin",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "manager": {
          "value": "1P01A7JNOWRLONI81IT5J6FZYM2IMLB72ZVL",
          "displayName": "Andy"
      }
  }, 
"urn:ietf:params:scim:schemas:extension:gainsight:2.0:User": {
        "IsSuperAdmin": false,
        "custom_roles": [
            "JO Admin",
            "CSM"
        ],
        "LicenseType": "Full"    }
}

Sample Success Response

 {
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU",
  "userName": "sample1234",
  "name": {
      "familyName": "Dee",
      "givenName": "JohnDeer"
  },
  "displayName": "JohnDeer Dee",
  "title": "Er",
  "locale": "de_DE",
  "timezone": "Europe/Berlin",
  "active": true,
  "emails": [
      {
          "value": "john@sample.com",
          "primary": true
      }
  ],
   "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71",
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ],
  "roles": [
                {
                    "value": "Data Team"
                },
                {
                    "value": "JO Admin"
                }
            ],
  "meta": {
      "resourceType": "User",
      "created": "2024-10-10T23:49:13Z",
      "lastModified": "2024-10-10T23:49:13Z",
      "location": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "manager": {
          "value": "1P01A7JNOWRLONI81IT5J6FZYM2IMLB72ZVL"
      }
  },
"urn:ietf:params:scim:schemas:extension:gainsight:2.0:User": {
        "IsSuperAdmin": false,
        "custom_roles": [
            "JO Admin",
            "CSM"
        ],
        "LicenseType": "Full"    }
}

SCIM Modify User APIs (Patch)

The SCIM Modify User APIs allow you to manage user attributes efficiently by updating specific fields without changing the entire user record. These APIs let you add, replace, or remove user attributes, and toggle a user’s status between active and inactive. Below are the key APIs used for modifying user attributes in Gainsight using SCIM.

  1. Add Value
  2. Replace Value
  3. Remove Value
  4. Inactive / Active Value

Fields Supported for Add/Remove/Replace:

Field Name Description
userName* If any field mapping for userName is present, the mapped field will be updated. Otherwise, the userName field itself will be updated.
emails*
  • If multiple email addresses are provided, one of them must be marked as primary: true. If no email is marked as primary, or if multiple emails are provided without specifying the primary email, the email update will be ignored.
  • If only one email address is provided and the primary field is not set, it will be considered the primary email by default.

  • If email-to-username mapping is enabled, updating the email will also update the user name whenever the email is changed.

  • The format "emails[value eq '%s'].type" is not supported.
manager The value must contain the GSID of the user assigned as the manager.
roles The roles provided in the input must exist in Gainsight. If they do, they will appended to the user's current roles list.
groups The provided groups will replace all existing groups for the user, adding them to the specified groups and removing them from all others. In groups value and display both attributes are not mandatory, providing either one is acceptable.
active* Setting this field to false will deactivate the user, removing their permission bundle, license type, and login credentials.
name.givenName* Updating the given name modifies the user's first name in Gainsight, while the name field, which stores the display name remains unchanged.
name.familyName* Updating the family Name modifies the user's last name in Gainsight, while the name field, which stores the display name remains unchanged.
displayName* Updating the display name directly modifies the name field in Gainsight.
locale* If the provided locale is invalid or unsupported by Gainsight, it will default to an environment-specific, configurable locale.
timezone* If the provided timezone is invalid or unsupported by Gainsight, it will default to an environment-specific, configurable timezone
title Accepts text values.
Custom attributes To add custom user attributes, ensure that all custom fields are included under the urn:ietf:params:scim:schemas:extension:gainsight:2.0:User namespace, as illustrated in the request payload below.

 Note: Fields marked with an asterisk (*) cannot be set to null or empty using any add, remove, or replace operation.

Add Value API

The Add Value API  is used to update specific fields or attributes of a resource by adding or modifying values without affecting the entire resource.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
        "op": "add",
         "path": "groups",
         "value": [
                {
                        "value":"1UG1LTOL3DUDWPQ5RKDL1ZO64BC9A6MFHKZE",
                        "display":"Support and Services"
                },
                {
                        "value":"1UG1LTOL3DUDWPQ5RKBYO2DNLVXPIQXZ7JJB",
                        "display":"CSM"
                }
        ]
      },
     {
          "op": "add",
          "path": "locale",
          "value": "en_US"
      },
      {
          "op": "add",
          "path": "timezone",
          "value": "America/New_York"
      },
      {
          "op": "add",
          "path": "title",
          "value": "mr"
      },
      {
          "op": "add",
          "path":
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
          "value" : "1P01A7JNOWRLONI81IM9FEYG2VA74C83T054"
      },
      {
          "op": "add",
          "path": "roles",
          "value": [
              {
                  "value": "Admin"
              }
          ]
      },
      {
            "op": "add",
            "path": "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User",
            "value": {
                "IsSuperAdmin": true,
                "LicenseType": "Viewer_Analytics",
                "custom_roles": [
                       "JO Admin",
                       "Data Team"                ]
            }
        }
  ]
}

Sample Success Response

204 No Content

Replace Value API

The Replace Value API is used to update or overwrite an existing value of a specific field or attribute within a resource.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
        {
        "op": "replace",
         "path": "groups",
         "value": [
             {
                "value":"1UG1LTOL3DUDWPQ5RKDL1ZO64BC9A6MFHKZE",
                 "display":"Support and Services"
            },
           {
                 "value":"1UG1LTOL3DUDWPQ5RKBYO2DNLVXPIQXZ7JJB",
                 "display":"CSM"
            }
         ]
      },
      {
          "op": "replace",
          "path": "active",
          "value": true
      },
      {
          "op": "replace",
          "path": "userName",
          "value": "cn100001"
      },
      {
          "op": "replace",
          "path": "name.givenName",
          "value": "Micheal"
      },
      {
          "op": "replace",
          "path": "name.familyName",
          "value": "Jac"
      },
      {
          "op": "replace",
          "path": "displayName",
          "value": "Micheal Jac"
      },
      {
          "op": "replace",
          "path": "locale",
          "value": "en_US"
      },
      {
          "op": "replace",
          "path": "timezone",
          "value": "America/New_York"
      },
      {
          "op": "replace",
          "path": "title",
          "value": "dr"
      },
      {
          "op": "replace",
          "path": "emails",
          "value": [
              {
                  "value": "Micheal@sample.com"             
              }
          ]
      },
      {
        "op": "replace",
  "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
      "value": {
        "value": "1P01A7JNOWRLONI81IH1WS0N5CT32MHVK8OE",
        "displayName": "Jane Smith"
       }
     },
      {
          "op": "replace",
          "path": "roles",
          "value": [
              {
                  "value": "Csm"
              }
          ]
      },
   {
            "op": "replace",
            "path": "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User",
            "value": {
                "IsSuperAdmin": true,
                "LicenseType": "Viewer_Analytics",
                "custom_roles": [
                       "JO Admin",
                       "Data Team"
                ]
            }        }
  ]
}

Sample Success Response

204 No Content

Remove Value API

The Remove Value API is used to delete or remove users from a group.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
     {
        "op": "remove",
         "path": "groups",
         "value": [
             {
                "value":"1UG1LTOL3DUDWPQ5RKDL1ZO64BC9A6MFHKZE",
                 "display":"Support and Services"
            },
           {
                "value":"1UG1LTOL3DUDWPQ5RKBYO2DNLVXPIQXZ7JJB",
                 "display":"CSM"
            }
         ]
      },    
      {
          "op": "remove",
          "path": "roles",
          "value": [
              {
                  "value": "CSM"
              }
          ]
      },
     {
            "op": "remove",
            "path": "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User.IsSuperAdmin"
        },
{
            "op": "remove",
            "path": "urn:ietf:params:scim:schemas:extension:gainsight:2.0:User.custom_roles"
          "value": [
                       "JO Admin"
                ]        }

  ]
}

Sample Success Response

204 No Content

Inactivate/Active API

The Inactivate/Activate API is used to change the status of a resource, toggling it between inactive and active states.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

{
    "schemas":
    [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations":
    [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ]
}

Sample Success Response

204 No content

SCIM GET API

The SCIM GET API is used to retrieve user or resource information from a system based on SCIM standards.

Method

GET

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU

Sample Request Body

204 No Content

Sample Success Response

{
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU",
  "userName": "sample1234",
  "name": {
      "familyName": "Dee",
      "givenName": "JohnDeer"
  },
  "displayName": "JohnDeer Dee",
  "title": "Er",
  "locale": "de_DE",
  "timezone": "Europe/Berlin",
  "active": true,
  "emails": [
      {
          "value": "john@sample.com",
          "primary": true
      }
  ],
  "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71",
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ],
  "roles": [
                {
                    "value": "Data Team"
                },
                {
                    "value": "JO Admin"
                }            ],
  "meta": {
      "resourceType": "User",
      "created": "2024-10-10T23:49:13Z",
      "lastModified": "2024-10-11T00:02:37Z",
      "location": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "manager": {
          "value": "1P01A7JNOWRLONI81IT5J6FZYM2IMLB72ZVL"
      }
  }
}

SCIM Search User API

The SCIM Search API is used to search for and retrieve multiple users or resources based on specified query parameters in a system.

Method

GET

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/users?filter=userName EQ sample1234&startIndex=1&count=5

Sample Request Body

204 No Content

Parameters

Parameter Type Required Description
filter String No

A filter expression to search for specific users. The expression must be in the format attribute equivalen value.

For Example: userName eq “sample12345"

Supported filter attribute names: userName, emails. value,externalId

Supported Operators: equal, not equals, starts with,  ends with, contains

Supports only with single attribute name search.
sortBy String No The attribute by which to sort the results. Example: userName.
sortOrder String No The order to sort results by, either asc for ascending or desc for descending. The default is ascending.
attributes String No A comma-separated list of attributes to return in the response. Example: userName, emails.
startIndex Number  No The index of the first result to return. The default is one.
count Number No
  • The maximum number of results to return. The default is 100.
  • If the count is negative or zero provided, only total results are provided.

Note

  • SCIM Create Group API Endpoint is not supported because groups are predefined in Gainsight. If a new Group is needed, it can be configured on the Gainsight side.
  • SCIM Update Group API Endpoint is not supported because groups are predefined in the Gainsight.

Sample Success Response

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "startIndex": 1,
  "itemsPerPage": 1,
  "totalResults": 1,
  "Resources": [
      {
          "schemas": [
              "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "id": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU",
          "userName": "sample1234",
          "name": {
              "familyName": "Dee",
              "givenName": "JohnDeer"
          },
          "displayName": "JohnDeer Dee",
          "active": true,
          "emails": [
              {
                  "value": "john@sample.com",
                  "primary": true
              }
          ],
      "groups": [
                {
                    "value": "1UG1H0NQJHYL5UUYRUOVHAIVLE6T4RYOSI71",
                    "display": "ITSpeciallist"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUHW61URSRJB05U836I2",
                    "display": "Support"
                },
                {
                    "value": "1UG1H0NQJHYL5UUYRUTDLYPRUDWA60SUXFD3",
                    "display": "Services"
                }
            ],
"roles": [
                {
                    "value": "Data Team"
                },
                {
                    "value": "JO Admin"
                }            ]
      }
  ]
}

SCIM Search Group API

The SCIM Search Group API is used to search for and retrieve information about groups within a system based on specified query parameters.

Method

GET

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Groups?startIndex=1&count=1&excludedAttributes=members&filter=displayName eq "ITSpeciallist"

Sample Request Body

204 No Content

Parameters

Parameter Type Required Description
filter String No

A filter expression to search for specific users. The expression must be in the format “attribute eq value". Example: displayName equivalent to ITSpeciallist.
excludedAttributes String No A comma-separated list of attributes to exclude from the response. Example: members.
startIndex Number  No The index of the first result to return. The default is one.
count Number No
  • The maximum number of results to return. The default is 100.
  • If the filter and count parameters are not provided in the request, two groups will be returned by default. Otherwise, the number of users specified by the count parameter will be returned.

Sample Success Response

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 5,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
      {
          "schemas": [
              "urn:ietf:params:scim:schemas:core:2.0:Group"
          ],
          "id": "584ddd3b-fbd5-47a9-981b-1aca2142eed9",
          "displayName": "ITSpecialList",
          "meta": {
              "resourceType": "Group",
              "created": "2024-10-11T05:49:37Z",
              "lastModified": "2024-10-11T05:49:37Z",
              "location": "https://<<tenant-url>>/v2/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9",
              "version": "599a5b7e8ad64cdd7a7fddb5557ea324"
          }
      }
  ]
}

SCIM Get Group API

The SCIM Get Group API is used to retrieve details of a specific group within a system.

Method

GET

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9

Sample Request Body

204 No Content

Sample Success Response

{
  "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "584ddd3b-fbd5-47a9-981b-1aca2142eed9",
  "displayName": "ITSpecialList",
  "meta": {
      "resourceType": "Group",
      "created": "2024-10-11T05:53:19Z",
      "lastModified": "2024-10-11T05:53:19Z",
      "location": "https://<<tenant-url>>/v2/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9",
      "version": "7cf9231ee35ff3a4e987a5bce915b712"
  },
  "members": [
      {
          "value": "1P01A7JNOWRLONI81ISXYOSQZ5YC5F3KE9HO",
          "type": "User",
          "display": "Veera Dasari",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81ISXYOSQZ5YC5F3KE9HO"
      },
      {
          "value": "1P01A7JNOWRLONI81I3S6KU8D3ZZHHJDWUHQ",
          "type": "User",
          "display": "Topalka IC",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81I3S6KU8D3ZZHHJDWUHQ"
      },
      {
          "value": "1P01A7JNOWRLONI81IAL72RRQJPSFUSLW3J4",
          "type": "User",
          "display": "Topalka Angelova",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IAL72RRQJPSFUSLW3J4"
      },
      {
          "value": "1P01A7JNOWRLONI81IQNE14TFML9Y8CT1GSC",
          "type": "User",
          "display": "Pavithra P Poojary",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IQNE14TFML9Y8CT1GSC"
      },
      {
          "value": "1P01A7JNOWRLONI81I15S7VLBPHY82IIJUY2",
          "type": "User",
          "display": "Pavithra P Poojary",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81I15S7VLBPHY82IIJUY2"
      },
      {
          "value": "1P01A7JNOWRLONI81IPV1R67XJ4MU7RBRIFU",
          "type": "User",
          "display": "Pavithra P Poojary",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IPV1R67XJ4MU7RBRIFU"
      },
      {
          "value": "1P01A7JNOWRLONI81I9GSAPKAD0ET20GKRBP",
          "type": "User",
          "display": "Pavithra P Poojary",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81I9GSAPKAD0ET20GKRBP"
      },
      {
          "value": "1P01A7JNOWRLONI81I4G1EY5PEQD3QJ75JZC",
          "type": "User",
          "display": "Kumar Sandeep",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81I4G1EY5PEQD3QJ75JZC"
      },
      {
          "value": "1P01A7JNOWRLONI81IHBEMC8TKLKWAHVK21V",
          "type": "User",
          "display": "testAddGroupMemberWithPATCH-patchedUser",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IHBEMC8TKLKWAHVK21V"
      },
      {
          "value": "1P01A7JNOWRLONI81I56I7KE2XG53QVM5O0P",
          "type": "User",
          "display": "scim test user2",
          "$ref":
"https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81I56I7KE2XG53QVM5O0P"
      },
      {
          "value": "1P01A7JNOWRLONI81IUZ33GJ53BY0DI7NO2U",
          "type": "User",
          "display": "Topalka Admin",
          "$ref": "https://<<tenant-url>>/v2/Users/1P01A7JNOWRLONI81IUZ33GJ53BY0DI7NO2U"
      }
  ]
}

SCIM Add Members to Group API

The SCIM Add Members to Group API is used to add users or resources to a specific group within a system.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "add",
          "path": "members",
          "value":
              [
                  {
                      "value": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
                  }
              ]
      }
  ]
}

Sample Success Response

204 No Content

SCIM Remove Members from Group API

The SCIM Remove Members from Group API removes all existing users from current group and add the users which are giving in the request payload.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "remove",
          "path": "members",
          "value":
              [
                  {
                      "value": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
                  }
              ]
      }
  ]
}

Sample Success Response

204 No Content

SCIM Replace Member from Group API

The SCIM Replace Members from Group API is used to replace users or resources from a specific group within a system.

Method

PATCH

Endpoint URL

https://<<tenant-url>>/v1/users/services/scim/Groups/584ddd3b-fbd5-47a9-981b-1aca2142eed9

Sample Request Body

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "replace",
          "path": "members",
          "value": {
              "members": [
                  {
                      "value": "1P01A7JNOWRLONI81IU0BZ8XA0AEVQ5J11CU"
                  }
              ]
          }
      }
  ]
}

Sample Success Response

204 No Content

SCIM User to GS User Default Mapping

The default mapping ensures that key user information is automatically synchronized between SCIM and Gainsight, facilitating seamless user management and reducing the need for manual updates. Each row in the table below describes the corresponding attributes from SCIM and their default target attributes in Gainsight, along with any relevant comments.

Source SCIM User attribute GS User Default Target Attribute Comments
ID ID  
externalId externalid__gc Based on SCIM user attributes mappings in Gainsight, GS SCIM API considers and adds value accordingly. This should be the String field in Gainsight.
userName userName*  
name.givenName
name.familyName		 firstName*
lastName*		  
displayName name*  
title title  
locale locale We are matching if the passed locale is supported by Gainsight else we are setting it to the default value.
timezone timezone We are matching if the passed timezone is supported by Gainsight else we are setting it to the default value.
active active  
emails[0…n].value.primary.true
(Or)
emails[0].value		 email* If primary absence it takes an email from the first entry of the value in the emails list.
groups Adds to groups in Gainsight  
manager
For example:

Ex: 

{

  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

    "manager": {

      "value": "<<gsUserId>>"

    }

  }

}

 manager We are expecting IDP to send the manager's GSID.
roles roles_gc Based on SCIM user attributes mappings in Gainsight, GS SCIM API considers and adds value accordingly. This should be a multipickList field in Gainsight.
nickName Not Supporting  
preferredLanguage Not Supporting  
profileUrl Not Supporting  
userType Not Supporting  
phoneNumbers Not Supporting  
password Not Supporting  
ims Not Supporting  
photos Not Supporting  
addresses Not Supporting  
entitlements Not Supporting  
x509Certificates Not Supporting  

Response Status Codes

The table below describes the common response status codes.

Code Status Description
200 OK Successful request with body content.
201 Created The request has succeeded and has led to the creation of a resource.
204 No Content Successful request without body content.
400 Bad Request The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized Authentication credentials were missing or incorrect or the SCIM feature was not enabled.
500 Bad Gateway Something went wrong on the server.

Error Responses

The following are the error responses:

Example: If the user is already present and has tried creating a duplicate user

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "",
    "detail": "The user already exists.",
    "status": 409
}

Example: If Gainsight UserId or GroupId sends invalid or empty.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "",
    "detail": "Oops, something went wrong.",
    "status": 500
}

Example: The Requested group does not exist in Gainsight.

 {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "",
    "detail": "The group does not exist.",
    "status": 409
}
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Custom Filter
    Admin Guides
    Draft Workflow
    Draft
  2. Tags
    1. M2M Auth
    2. OAuth
    3. SCIM API
    4. Search Group UPI
    5. User Group API