Add Users

Adds users to a Kintone environment.
Note that once a user is added with this API, the Update User Services API needs to be used against this user for the user to have access to Kintone services.

For more information on the Update User Services API, refer to the following article:
Update User Services

Method	POST
URL	https://{subdomain}.kintone.com/v1/users.json
Authentication	Password Authentication , Session Authentication
Content-Type	application/json

Permissions
Request Parameters
Sample Request
Response Parameters
Sample Response
Limitations

Permissions

Only Administrators can use this API.

For more information on Administrators, refer to the following article:
Types of Administrators

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	Value	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. The default is `true`. State `true` for active users, and `false` for inactive users.
password	String	Yes	The password. The maximum limit is 128 characters. Whitespaces are not allowed.
name	String	Yes	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.
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 Arrays	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


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',
      'sortOrder': 12,
      'customItemValues': [
        {
          'code': 'userNameKey',
          'value': 'jf'
        }
      ]
    }
  ]
};
kintone.api(kintone.api.url('/v1/users.json', true), 'POST', 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


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',
      '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('POST', 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
- Importing from a file

API Docs