User Management (GraphQL)

To update users' data, Starmind offers a GraphQL 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.

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

User Attributes

Parameter	Type	Nullable	Required for creation	Description
email	string	✗	✓	max. 191 characters.
firstname	string	✗	✓	max. 50 characters.
lastname	string	✗	✓	max. 50 characters.
externalId	string	✗	✗	max. 250 characters. Must be an unique identifier.
languageId	languageId (language code)	✗	✗	The interface language for the user.
location	string	✓	✗	Location-specific information (department, etc.). Max. 100 characters.
about	text	✓	✗	Text to describe the user. This information is showed in the user profile. Max. 100 characters.
countryId	string	✓	✗	Country code in ISO 3166-2 format like ch, de, us.
company	text	✓	✗	Company of the user. Max. 255 characters.
department	text	✓	✗	Department of the user. Max. 255 characters.
position	text	✓	✗	Position of the user. Max. 255 characters.
employmentStart	datetime	✓	✗	The 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":"{{position}}", 
        "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}}"
	} 
}

Reactivate User

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

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 anonymized. This will deactivate the user and schedule the deletion for 14 days in the future. This allows for a grace period of 2 weeks until which a delete action can be undone. Once the 2 weeks have passed, the user becomes unrecoverable forever.

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}}"
  }
}

Cancel Delete

Replace the {{user_id}} with the id of the user for which anonymization should be cancelled. This will only work during the 2 week grace period after a delete was initiated.

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

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

Body  
{ 
  "query":"mutation cancelDelete($globalUserId: UUID!) {cancelDelete(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}}"
    }
  }
}