API Docs

Update Users

Updates users of a Kintone environment.

MethodPUT
URLhttps://{subdomain}.kintone.com/v1/users.json
Authentication API Token Authentication , Password Authentication , Session Authentication
Content-Typeapplication/json

Contents

Permissions

Only Administrators can use this API.

For more information on Administrators, refer to the following article:
Types of Administrators (External link)

Request Parameters

A users array consisting of an object formed by the below properties is to be specified in the request. Up to 100 users can be updated.

Parameter Type Required Description
code String Yes The User Code (log-in name).
The maximum limit is 128 characters.
Values consisting of only whitespaces or null are not allowed.
valid Boolean Optional The Status of the user.
State true for active users, and false for inactive users.
password String Optional The password.
The maximum limit is 128 characters.
Whitespaces are not allowed.
name String Optional The display name.
The maximum limit is 128 characters.
Values consisting of only whitespaces or null are not allowed.
surName String Optional The Surname.
The maximum limit is 128 characters.
givenName String Optional The Given Name.
The maximum limit is 128 characters.
surNameReading String Optional The Phonetic Surname.
The maximum limit is 128 characters.
This setting is not displayed when editing user information on the Departments & Users page for kintone.com domains.
givenNameReading String Optional The Phonetic Given Name.
The maximum limit is 128 characters.
This setting is not displayed when editing user information on the Departments & Users page for kintone.com domains.
localName String Optional The Localized Name.
The maximum limit is 128 characters.
This setting is not displayed when editing user information on the Departments & Users page for kintone.com domains.
localNameLocale String Optional The Language for the Localized Name.
The maximum limit is 128 characters.
This setting is not displayed when editing user information on the Departments & Users page for kintone.com domains.
timezone String Optional The user's timezone.
An error will occur if left blank.
The maximum limit is 256 characters.
locale String Optional The language settings.
Specify one of the following:
  • en: English
  • ja: Japanese
  • zh: Chinese (Simplified)
  • zh-TW: Chinese (Traditional)
  • es: Spanish
  • pt-BR: Brazilian Portuguese
  • th: Thai
  • auto: if set as auto or left blank, the User's Language settings will be set to Use Web browser settings
description String Optional The description of the user, displayed on the About Me section of the profile.
The maximum limit is 1000 characters.
phone String Optional The Phone number.
The maximum limit is 100 characters.
mobilePhone String Optional The Mobile phone number.
The maximum limit is 100 characters.
extensionNumber String Optional The Extension number.
The maximum limit is 100 characters.
email String Optional The E-mail address.
The maximum limit is 256 characters.
callto String Optional The Skype name.
Limitations are based on limitations of Skype names.
url String Optional URL
The maximum limit is 256 characters.
employeeNumber String Optional The Employee ID.
The maximum limit is 100 characters.
birthDate Date Optional The Birthday.
Specify the Date in the format of YYYY-MM-DD or an empty string.
joinDate Date Optional The Hire Date.
Specify the Date in the format of YYYY-MM-DD or an empty string.
primaryOrganization Number Optional The Priority Department of the User.
Specify the Department ID. Set to null if there is no Priority Department.
The User needs to belong to a Department for this parameter to be used.
sortOrder Number Optional The priority of the user in lists of users. Users are sorted in the list in ascending order based on this number.
Numbers from 0 to 99999999 can be used.
customItemValues customItemValue Array Optional A list of pairs of Custom Item codes and Custom Item values for Custom Fields.

Sample Request

JavaScript Using kintone.api() 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

var body = {
  'users': [
    {
      'code': 'Administrator',
      'valid': true,
      'password': 'xxxyyyzzz',
      'name': 'Administrator',
      'surName': 'a',
      'givenName': '',
      'surNameReading': '',
      'givenNameReading': '',
      'localName': '',
      'localNameLocale': 'en',
      'timezone': 'America/Los_Angeles',
      'locale': 'en',
      'description': '',
      'phone': '',
      'mobilePhone': '',
      'extensionNumber': '',
      'email': '',
      'callto': '',
      'url': '',
      'employeeNumber': '123',
      'birthDate': '1980-01-01',
      'joinDate': '2015-04-01',
      'primaryOrganization': 1,
      'sortOrder': 12,
      'customItemValues': [
        {
          'code': 'userNameKey',
          'value': 'jf'
        }
      ]
    }
  ]
};
kintone.api(kintone.api.url('/v1/users.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

var body = {
  'users': [
    {
      'code': 'Administrator',
      'valid': true,
      'password': 'xxxyyyzzz',
      'name': 'Administrator',
      'surName': 'a',
      'givenName': '',
      'surNameReading': '',
      'givenNameReading': '',
      'localName': '',
      'localNameLocale': 'en',
      'timezone': 'America/Los_Angeles',
      'locale': 'en',
      'description': '',
      'phone': '',
      'mobilePhone': '',
      'extensionNumber': '',
      'email': '',
      'callto': '',
      'url': '',
      'employeeNumber': '123',
      'birthDate': '1980-01-01',
      'joinDate': '2015-04-01',
      'primaryOrganization': 1,
      'sortOrder': 12,
      'customItemValues': [
        {
          'code': 'userNameKey',
          'value': 'jf'
        }
      ]
    }
  ],
  // CSRF TOKEN: Needs to be set when using API (POST, PUT, DELETE) from Kintone
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/v1/users.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Response Parameters

An empty JSON object will be returned.

Sample Response

1

{}

Limitations

  • It is not recommended run this API while performing the following operations on the Users & System Administration page:
    • Updates to users on the Departments & Users page
      For more information, refer to the following article:
      Managing Users (External link)
    • Importing from a file