User Management - GraphQL

To update users' data, Starmind offers a Graph QL API. This API can be used to create, update, deactivate, restore or delete users.

Each request requires an access token, that authenticates the requester. Information about authentication can be found here: REST-API Authentication.

User unique_id is requested when modifying a user. Such value can be found using the "Search User" method

base_domain is the base URL of your application (format: customer.starmind.com)

User Attributes

ParameterTypeNullableRequired for creationDescription
emailstringmax. 191 characters.
firstnamestringmax. 50 characters.
lastnamestringmax. 50 characters.
externalIdstringmax. 250 characters.
languageIdlanguageId (language code)The interface language for the user.
locationstringLocation-specific information (department, etc.). Max. 100 characters.
abouttextText to describe the user. This information is showed in the user profile. Max. 100 characters.
countryIdstringCountry code in ISO 3166-2 format like ch, de, us.
companytextCompany of the user. Max. 255 characters.
departmenttextDepartment of the user. Max. 255 characters.
positiontextPosition of the user. Max. 255 characters.
employementStartdatetimeThe employment start date of the user in the format yyyy-mm-dd.

Search User

Replace the search term with e.g. the email address of the user or their externalId.

*inputs:

searchText(required): set as "" to search for all users

offset (Optional): default value is 0

limit (Optional): default value is 100*

Header
Content-Type: application/json 
Authorization: Bearer {{access_token}}

Body 
{
  "query":"query getUsers($searchText: String, $offset: Offset, $limit: Limit) {
        users(searchText: $searchText, offset: $offset, limit:$limit){
                globalUserId,
                externalId, 
                firstname, 
                lastname, 
                email, 
                location,
                department,
                position,
                gender,
                about,
                languageId,
                employmentStart,
                isSystem,
                isHidden,
                avatarUrl,
                dateDeleted
        }
    }",
    "variables":{ 
        "searchText":"{search_term}",
        "offset":"{offset}",
        "limit":"{limit}"
    }
}

Update User

Only send the attributes which should be changed. The list of the attributes needs only be adjusted in the query. Please note that the attribute "globalUserId" is mandatory, as it is how the system will identify the user to update.

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1   

Header 
Content-Type: application/json  
Authorization: Bearer {{access_token}}

Body
{
  "query":"mutation updateUser($updateUserInput: UpdateUserInput!) {updateUser(input: $updateUserInput) {firstname, lastname, email, externalId, languageId, countryId, gender,company,department,position,location, about, globalUserId}", 
  "variables":{
      "updateUserInput":{ 
        "firstname":"{{first_name}}", 
        "lastname":"{{last_name}}", 
        "externalId":"{{externalId}}",
        "languageId":"{{language_id}}", 
        "location":"{{location}}", 
        "company":"{{company}}", 
        "position":"{{positiom}}", 
        "department":"{{department}}", 
        "countryId":"{{country_id}}", 
        "about":"{{User description}}",
    "globalUserId":"{{globalUserId}}"
    }
  }
}

If the email address should be updated the following request should be used:

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1

Header 
Content-Type: application/json 
Authorization: Bearer {{access_token}}

Body
{
    "query": "mutation updatePrivilegedUserAndEmail( $updateUserEmailInput: UpdateUserEmailInput!) {updateUserEmail(input: $updateUserEmailInput) {globalUserId, email}}",
    "variables": {
            "updateUserEmailInput": {
                "email": "{email}",
                "globalUserId": "{global-user-id}"
            }
    }
}

Deactivating User

Replace the {user_id} with the id of the user which should be deactivated.

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1

Header 
Content-Type: application/json 
Authorization: Bearer {{access_token}}

Body 
{
    "query":"mutation DeactivateUser($globalUserId: UUID!) {deactivateUser(globalUserId: $globalUserId) { globalUserId}}", 
    "variables":{ 
        "globalUserId":"{{user_id}}"
    } 
}

Restore User

Replace the {{user_id}} with the id of the user which should be restored.

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1    

Header  
Content-Type: application/json   
Authorization: Bearer {{access_token}}

Body  
{  
  "query":"mutation reactivateUser($globalUserId: UUID!) {reactivateUser(globalUserId: $globalUserId) { globalUserId}}", 
  "variables":{
    "globalUserId":"{{user_id}}"
  }
}

Delete User (Anonymize)

Replace the {{user_id}} with the id of the user which should be anonymised.

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1    

Header  
Content-Type: application/json   
Authorization: Bearer {{access_token}} 

Body  
{ 
  "query":"mutation deleteUser($globalUserId: UUID!) {deleteUser(globalUserId: $globalUserId) { globalUserId}}", 
  "variables":{
    "globalUserId":"{{user_id}}"
  }
}

Create User

Adjust the variables for the user (firstname, lastname, email).

POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1      

Header
Content-Type: application/json
Authorization: Bearer {{access_token}}

Body

{
  "query":"mutation createUser($createUserInput: CreateUserInput!) { createUser(input: $createUserInput) { globalUserId }}",
  "variables":{ 
    "createUserInput":{
      "firstname":"{{first_name}}", 
      "lastname":"{{last_name}}", 
      "email":"{{email}}",
      "externalId":"{{externalId}}"
    }
  }
}