GET/users/search

Search for members.
Performs a partial match search based on the Name Information (userName), Nickname (nickName), member's email address (email), Phone number(telephone), Mobile Phone number (cellPhone), Team name (organizations[].orgUnits[].orgUnitName), and Task (task).
Fields set to hidden in the service are excluded from search results.
If the search term contains a space, the member's email address (email) will be excluded from the search results. 。
For the ember's email address (email), if the search term contains an "@", the whole email address is searched; if it does not contain an "@", the localpart is searched. For phone numbers and mobile phone numbers, only the digits are extracted from the search terms, and the search is performed only if the number is four digits or longer.

Authorization

oauth2

OAuth 2.0 authentication.
For more information, see Authentication and Authorization.

Scope

user
user.read
directory
directory.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/users/search

Query Parameters

ParameterTypeDescription
domainId integer 

Domain ID


example : 10000001
format : int32 
query string 

Search term


required
minLength : 1
maxLength : 100 
orderBy string 

Sort by: userName
Separate sort criteria and order with a space (%20)


default : userName%20asc
Allowed values : userName%20asc, userName%20desc 
count integer 

Number of items to get


default : 100
minimum : 1
maximum : 100
example : 100 
cursor string 

cursor


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

OK

PropertyTypeDescription
users array (UserResponse) 

Member information

 
responseMetaData object (responseMetaData) 

Response metadata

 

UserResponse

PropertyTypeDescription
domainId integer 

Domain ID


required
format : int32 
userId string 

Member ID


readOnly : true 
userExternalKey string 

Customer's member external key

Some special characters, %, \, #, /, ? are not allowed.


maxLength : 100
nullable : true 
isAdministrator boolean 

Indicates whether the member is the domain administrator.


readOnly : true 
isPending boolean 

Indicates whether the member is pending.


readOnly : true 
isSuspended boolean 

Indicates whether the member is suspended.


readOnly : true 
isDeleted boolean 

Indicates whether the member is deleted.


readOnly : true 
isAwaiting boolean 

Indicates whether the member is active.


readOnly : true 
leaveOfAbsence object (leaveOfAbsence) 

readOnly : true 
suspendedReason string 

Reason for suspension

  • MASTER: Suspended by the administrator.
  • LOGIN_FAIL: Login failed.

Allowed values : MASTER, LOGIN_FAIL
readOnly : true
nullable : true 
email string 

Account. It is the same as the member's email address (id@domain for Standard, id@group for Advanced).

  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter or a number.
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 40 characters long and can only contain English letters, numbers, dot (.), hyphen (-), and underscore (_).
  • Neither "admin" nor "administrator" can be used as the localpart.

required
maxLength : 90 
userName object (userName) 

Name information


required 
i18nNames array (Useri18nName) 

List of multilingual names


minItems : 0 
nickName string 

Nickname. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~.


maxLength : 100
nullable : true 
privateEmail string 

Personal email address.

  • It is required if SSO is not enabled and passwordConfig.passwordCreationType is MEMBER.
  • It is required if the member is the super admin.
  • The email address must be valid. localpart@domain restrictions
  • The local part can be up to 64 characters long.
  • The domain name can be up to 253 characters long.

maxLength : 256
nullable : true 
aliasEmails array (string) 

List of email aliases.

  • An email alias can be up to 90 characters long.
  • The format is localpart@domain.
  • The localpart must start with a lowercase English letter or a number.
  • The localpart cannot start or end with a dot (.), and cannot contain two or more consecutive dots.
  • The localpart can be between 2 and 40 characters long and can only contain English letters, numbers, dot (.), hyphen (-), and underscore (_).

minItems : 0
maxItems : 10 
employmentTypeId string 

Employment type ID. Specify this parameter using the Enable employment types API operation.

  • Employment type ID
  • Employment type's ExternalKey (externalKey:{employmentTypeExternalKey})

nullable : true 
employmentTypeExternalKey string 

Employment type external key


maxLength : 100
readOnly : true
nullable : true 
employmentTypeName string 

Employment type name


readOnly : true
nullable : true 
userTypeId string 

User type ID. It is available only if useUserType of the "Enable user types" API operation is "true". If not specified, "no user type" applies.

  • User type ID
  • User type's ExternalKey (externalKey:{userTypeExternalKey})

nullable : true 
userTypeExternalKey string 

User type external key


maxLength : 100
readOnly : true
nullable : true 
userTypeName string 

User type name


readOnly : true
nullable : true 
userTypeCode string 

User type code. It can include any combination of alphabetic characters (A-Z, a-z), numbers (0-9), or underline symbols (_) and can be up to 50 characters long. It must start with an English letter.


maxLength : 50
readOnly : true
nullable : true 
searchable boolean 

Indicates whether to enable auto-complete and search (default: true).


default : true 
organizations array (UserOrganization) 

List of domains (companies) to which the member belongs, including both the primary and secondary positions.


minItems : 0 
telephone string 

Phone number. Only numbers with the following characters are allowed: - * # + P T ( )


maxLength : 100
pattern : ^(?=.*[0-9])[0-9+\-*#PTpt()\u3000]{0,100}
nullable : true 
cellPhone string 

Mobile phone number. Only numbers with the following characters are allowed: - * # + P T ( )


maxLength : 100
pattern : ^(?=.*[0-9])[0-9+\-*#PTpt()\u3000]{0,100}
nullable : true 
location string 

Office location


maxLength : 100
nullable : true 
task string 

Task


maxLength : 100
nullable : true 
messenger object (messenger) 

Messenger information


nullable : true 
birthdayCalendarType string 

Birthday type.

  • SOLAR: Solar
  • LUNAR: Lunar

Allowed values : SOLAR, LUNAR
nullable : true 
birthday string 

Birthday in YYYY-MM-DD format


maxLength : 10
nullable : true 
locale string 

Language code


Allowed values : ko_KR, ja_JP, en_US, zh_CN, zh_TW 
hiredDate string 

Date of hire in YYYY-MM-DD format


maxLength : 10
nullable : true 
timeZone string 

Timezone


example : Europe/Berlin 
customFields array (UserCustomField) 

Note

  • Please use customProperties instead of this parameter.
  • Using this parameter prevents you from accessing new features only available with the Add member custom properties API operation.

minItems : 0
maxItems : 50
deprecated : true 
customProperties object (customProperties) 

Member custom properties. You need to add a member custom property first using the Add member custom properties API operation.
The key of customProperties is the value of propertyName you specified in the Add custom field schemas API operation, which is a variable.
The value of customProperties differs in type depending on the propertyType and multiValued values of the field (see the description of each type in oneOf of CustomProperties for details). In addition, customProperties allows you to specify multiple custom properties together.

 
relations array (UserRelation) 

List of related contacts


minItems : 0
maxItems : 10 
activationDate string 

Account activation date (ISO-8601 format, YYYY-MM-DDThh:mm:ssTZD)

  • Can only be set to a date on or after the next day.
  • Can only be set to a date within 365 days from today.
  • If it is null, the account is activated immediately.

maxLength : 25
nullable : true 
employeeNumber string 

Employee number


minLength : 1
maxLength : 20
nullable : true 

leaveOfAbsence

PropertyTypeDescription
startTime string 

Start time ISO-8601


nullable : true 
endTime string 

End time ISO-8601


nullable : true 
isLeaveOfAbsence boolean 

Indicates whether the member is taking a leave of absence.
It is "true" if the member is, and "false" if the member is not or a leave of absence is scheduled.

 

userName

PropertyTypeDescription
lastName string 

Last name. The full name can be up to 80 characters long. Either lastName or firstName must be specified. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~.


maxLength : 80
nullable : true 
firstName string 

First name. The full name can be up to 80 characters long. Either lastName or firstName must be specified. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~.


maxLength : 80
nullable : true 
phoneticLastName string 

Last name in Furigana. Katakana is allowed only.


maxLength : 100
nullable : true 
phoneticFirstName string 

First name in Furigana. Katakana is allowed only.


maxLength : 100
nullable : true 

Useri18nName

PropertyTypeDescription
language string 

Language code


Allowed values : ko_KR, ja_JP, zh_CN, zh_TW, en_US 
firstName string 

First name in the language. The last name is followed by the first name in the organization chart. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~.


maxLength : 100
nullable : true 
lastName string 

Last name in the language. The last name is followed by the first name in the organization chart. The allowed special characters are ! @ & ( ) - _ + [ ] { } , . / # ' ` ^ ~.


maxLength : 100
nullable : true 

UserOrganization

PropertyTypeDescription
domainId integer 

Domain ID


required
format : int32 
primary boolean 

Indicates whether it is the primary domain.

Make sure that you have one primary item (primary: true). If not specified, the first item automatically becomes primary.


required 
userExternalKey string 

Caution

  • It references the top-level userExternalKey value instead of organizations[].userExternalKey.
  • When a member is added, updated, or partially updated, the value is ignored even if it is passed.

Customer's member external key

Some special characters, %, \, #, /, ? are not allowed.


maxLength : 100
nullable : true 
email string 

Email address.
Use this parameter to set two different email addresses for the primary and secondary positions.
Neither "admin" nor "administrator" can be used as the localpart.


maxLength : 90 
levelId string 

Job level ID. Specify this parameter using the "Enable job levels" API operation.

  • Job level ID (levelId)
  • Job level's ExternalKey (externalKey:{levelExternalKey})

nullable : true 
levelExternalKey string 

Customer's job level external key


maxLength : 100
readOnly : true
nullable : true 
levelName string 

Job level name


readOnly : true
nullable : true 
executive boolean 

Indicates whether the member is an executive or not.


readOnly : true 
organizationName string 

Company name


readOnly : true 
orgUnits array (orgUnit) 

List of teams


minItems : 0
maxItems : 30 

orgUnit

PropertyTypeDescription
orgUnitId string 

Team ID

  • Team ID (orgUnitId)
  • Team's ExternalKey (externalKey:{orgUnitExternalKey})

required 
orgUnitExternalKey string 

Customer's team external key


maxLength : 100
readOnly : true
nullable : true 
orgUnitName string 

Team name


readOnly : true 
orgUnitEmail string 

Team email address


readOnly : true 
primary boolean 

Indicates whether it is the primary team.

Make sure that you have one primary item (primary: true). If not specified, the first item automatically becomes primary.


required 
positionId string 

Position ID. It is available only if usePosition of the "Enable Positions" API operation is "true". If not specified, "no position" applies.

  • Position ID (positionId)
  • Position's ExternalKey (externalKey:{positionExternalKey})

nullable : true 
positionExternalKey string 

Customer's position external key


maxLength : 100
readOnly : true
nullable : true 
positionName string 

Position name


readOnly : true
nullable : true 
isManager boolean 

Indicates whether the member is a team leader (default: false). If it is "true" and a team leader already exists, the member replaces them, and the previous team leader is relieved of their duties.


default : false 
visible boolean 

Indicates whether to make the member visible (default: true). It indicates whether to make the member visible in the organization chart.


default : true 
useTeamFeature boolean 

Indicates whether to use the team features (default: true). Use this parameter to restrict a member's use of the team features for security purposes, such as: receiving messages, sharing files and receiving team emails in the team's message room. If it is "true", the member can join the team's message room (Message/Note/Calendar/Folder) and use the following team features:

  • Receive email messages sent to the team.
  • Receive calendar events shared to the team.
  • View the team calendar.
  • View files in the drive shared to the team.
  • View boards with the permissions given to the team.
  • Respond to surveys of the team.
  • Become a member of the groups which the team belongs to. If it is "false", all the team features described above are disabled. To prevent the member from using the team features, set this parameter to "false".

default : true 

messenger

PropertyTypeDescription
protocol string 

Messenger protocol

  • LINE: LINE
  • FACEBOOK: Facebook
  • X: X (formerly Twitter)
  • CUSTOM: Custom protocol

required
Allowed values : LINE, FACEBOOK, X, CUSTOM 
customProtocol string 

A user specified value when the protocol parameter is CUSTOM.


maxLength : 100 
messengerId string 

Messenger ID


required
minLength : 1
maxLength : 100 

UserCustomField

PropertyTypeDescription
customFieldId string 

Custom field ID

  • Resource ID generated when a custom field is created.
  • Customer's external key externalKey:externalKey

required 
customFieldExternalKey string 

Custom field external key


maxLength : 100
readOnly : true
nullable : true 
value string 

Custom field's text to display. It is required if the custom field type is STRING.


maxLength : 100
nullable : true 
link string 

URL when the custom field type is LINK.

  • link must be specified.
  • link must be set to a valid URL.
  • If value is "Homepage1" and link is "https://www.unicef.org":
    <a href = "https://www.unicef.org">Homepage1</a>
  • If only link is specified, it is displayed as text.

maxLength : 300
nullable : true 

customProperties

PropertyTypeDescription
propertyName string 

If propertyType is STRING and multiValued is false


maxLength : 100 
array (string) 

If propertyType is STRING and multiValued is true


maxItems : 10 
string 

If propertyType is STRING, multiValued is false, and options exists, It is one of the options, optionName.

 
array (string) 

If propertyType is STRING, multiValued is true, and options exists, it is one of the options, optionName.


maxItems : 10 
string 

If propertyType is DATE and multiValued is false, it is in the YYYY-MM-DD format.


pattern : YYYY-MM-DD
format : date 
array (string) 

If propertyType is DATE and multiValued is true, it is in the YYYY-MM-DD format.


maxItems : 10 
integer 

If propertyType is INTEGER and multiValued is false


minimum : 0 
array (integer) 

If propertyType is INTEGER and multiValued is true


maxItems : 10 
object (CustomPropertyLink) 

If propertyType is LINK and multiValued is false

  • link must be specified.
  • link must be set to a valid URL.
  • If text is 'Homepage1' and link is 'https://www.unicef.org':
    <a href = "https://www.unicef.org">Homepage1</a>
  • If link is specified but text is not, the link itself is displayed as the link text.
 
array (CustomPropertyLink) 

If propertyType is LINK and multiValued is true

  • Either text or link or both must be specified.
  • If text is 'Homepage1' and link is 'https://www.unicef.org':
    <a href = "https://www.unicef.org">Homepage1</a>
  • If text is specified but link is not, no hyperlink is created.
  • If link is specified but text is not, the link itself is displayed as the link text.

maxItems : 10 

CustomPropertyLink

PropertyTypeDescription
text string 

Text


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 

UserRelation

PropertyTypeDescription
relationUserId string 

Related contact member ID

 
relationName string 

Relation name


maxLength : 50 
externalKey string 

externalKey


maxLength : 100
readOnly : true
nullable : true 

responseMetaData

PropertyTypeDescription
nextCursor string 

Cursor value for pagination

 

Response Example

example

1{2  "users": [3    {4      "domainId": 10000001,5      "userId": "userf7da-f82c-4284-13e7-030f3b4c756x",6      "userExternalKey": "USER_EXT_01",7      "isAdministrator": false,8      "isPending": false,9      "isSuspended": false,10      "isDeleted": false,11      "isAwaiting": true,12      "email": "localpart@example.com",13      "userName": {14        "lastName": "last",15        "firstName": "first"16      },17      "i18nNames": [],18      "nickName": "nickname",19      "privateEmail": "private.works@example.com",20      "aliasEmails": [],21      "searchable": true,22      "organizations": [23        {24          "domainId": 10000001,25          "primary": true,26          "email": "localpart@example.com",27          "levelId": "levelaa7-b824-4937-66af-042f1f43cefa",28          "levelName": "level",29          "executive": false,30          "organizationName": "org",31          "orgUnits": [32            {33              "orgUnitId": "orgunitf-f27f-4af8-27e1-03817a911417",34              "orgUnitEmail": "team01@example.com",35              "orgUnitName": "orgUnit1",36              "primary": true,37              "positionId": "position-7027-4a02-b838-6f52b5e38db7",38              "positionName": "position",39              "isManager": true,40              "visible": true,41              "useTeamFeature": true42            }43          ]44        }45      ],46      "telephone": "031-1234-5678",47      "cellPhone": "010-1234-5678",48      "location": "green building",49      "task": "mytask",50      "messenger": {51        "protocol": "LINE",52        "messengerId": "lineid"53      },54      "birthdayCalendarType": "SOLAR",55      "birthday": "2000-01-01",56      "locale": "en_US",57      "hiredDate": "2020-01-01",58      "timeZone": "America/New_York",59      "leaveOfAbsence": {60        "isLeaveOfAbsence": false61      },62      "customProperties": {63        "string_single": "hiking",64        "string_multi": [65          "hiking",66          "swimming"67        ],68        "string_single_option": "option_cooking",69        "string_multi_option": [70          "option_cooking",71          "option_piano"72        ],73        "date_single": "2025-03-23",74        "date_multi": [75          "2025-03-23",76          "2025-03-24"77        ],78        "integer_single": 123,79        "integer_multi": [80          123,81          45682        ],83        "link_single": {84          "text": "worksmobile",85          "link": "https://contact.worksmobile.com"86        },87        "link_multi": [88          {89            "text": "worksmobile",90            "link": "https://contact.worksmobile.com"91          },92          {93            "text": "line",94            "link": "https://www.line.me/"95          }96        ]97      },98      "relations": [99        {100          "relationUserId": "userfd-fc09-4a57-ab38-03dc6c425e09",101          "relationName": "Manager",102          "externalKey": "ExternalKeyValue"103        }104      ],105      "activationDate": "2030-11-12T09:30:00+09:00",106      "employeeNumber": "employee1234"107    }108  ],109  "responseMetaData": {110    "nextCursor": "JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA=="111  }112}