# User resource introduction

Users are basic resources in the contacts and correspond to member entities in the enterprise organizational structure.

## Basic concepts

Before calling the Contacts API, it is recommended that you understand the following basic concepts.

### User ID

When calling the Contacts API, you will use multiple identities of the user, including `user_id`, `open_id` and `union_id`.

- user_id is the user's identity within a certain tenant.
- open_id is the user's identity within an application.
- Union_id is the user's identity in multiple applications developed by the same application service provider.

You can choose the appropriate user ID based on the actual application scenario. For example, if an application service provider wants to query whether a user under the current application is using other applications developed by it, it can query and determine based on the user's union_id.

- For a detailed introduction to user identity, see [User Identity Overview](https://open.feishu.cn/document/home/user-identity-introduction/introduction).
- For how to choose a user ID, please refer to [How to choose which ID to use](https://open.feishu.cn/document/home/user-identity-introduction/user-id).

### User status

When calling the Contacts API, you may query the user's multiple statuses (The `status` parameter can be used to call the [Get single user information](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get) and [Get user information in batches](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch) interfaces to query the user status), including whether it is activated, suspended, resigned, actively logged out, and not joined. The conversion relationship between various user statuses is shown in the figure below.

![Userstatus](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/672edc11eec4251107f3c25ee3903c7a_pc7UPVP2A4.png?height=1008&lazyload=true&maxWidth=700&width=2928)

##  Field description

Parameter | Type | Description
---|---|---
user_id | string | The unique identifier of the user within the tenant. user_id can be customized or randomly generated by the system. For a detailed description of user ID, see [User Identity Overview](https://open.feishu.cn/document/home/user-identity-introduction/introduction).<br>**Data validation rules for a custom `user_id`**:<br>- Maximum length: `64` characters<br>- Regular validation: No spaces are included<br>**Example value**: "u273y71"<br>**Required field scopes**:<br>Obtain user ID(contact:user.employee_id:readonly)
open_id | string | The unique identifier of the user within the application. The open_id of the same user in different applications is different. For a detailed description of user ID, see [User Identity Overview](https://open.feishu.cn/document/home/user-identity-introduction/introduction).<br>**Example value**: "ou_7dab8a3d3cdcc9da365777c7ad535d62"
union_id | string | The unique identifier of a user in multiple applications developed by the same application service provider. Application developers can associate the same user in multiple applications they develop through the user's union_id. For a detailed description of user ID, see [User Identity Overview](https://open.feishu.cn/document/home/user-identity-introduction/introduction).<br>**Example value**: "on_cad4860e7af114fb4ff6c5d496d1dd76"
name | string | User name. Length cannot exceed 255 characters.<br>**Example value**: "John"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's basic information(contact:user.base:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
en_name | string | English name. Length cannot exceed 255 characters.<br>**Example value**: "John"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's basic information(contact:user.base:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
email | string | Email.<br>**Example value**: "zhangsan@gmail.com"<br>**Required field scopes**:<br>Obtain user's email information(contact:user.email:readonly)
mobile | string | Mobile number.<br>**Example value**: "13011111111"<br>**Required field scopes**:<br>Obtain user's mobile number(contact:user.phone:readonly)
mobile_visible | boolean | Whether the mobile phone number is visible.<br>**Optional values are**:<br>- true: visible.<br>- false: invisible. When invisible, organization employees will not be able to view the employee's mobile number.<br>**Default value**: true<br>**Example value**: false
gender | int | Gender.<br>**Example value**: 1<br>**Optional values are**:<br>- 0: Unknown<br>- 1: Male<br>- 2: Female<br>- 3: Other<br>**Required field scopes (Satisfy any)**:<br>Obtain user's gender(contact:user.gender:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
avatar_key | string | The file key of the avatar. You can upload and obtain the avatar file Key through the [Upload Image](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create) interface.<br>**Example value**: "2500c7a9-5fff-4d9a-a2de-3d59614ae28g"
department_ids | string\[\] | List of IDs of departments to which the user belongs. For detailed description of department resources, please refer to [Department Resource Introduction](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview).<br>**Example value**: od-4e6ac4d14bcd5071a37a39de902c7141
leader_user_id | string | User ID (open_id) of the user's direct manager.<br>**Example value**: "ou_7dab8a3d3cdcc9da365777c7ad535d62"
city | string | City.<br>**Example value**: "Hangzhou"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
country | string | Country or region code. For the specific code, refer to the [country/region code list](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/country-code-description).<br>**Example value**: "CN"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
work_station | string | Seat ID.<br>**Example value**: "North building-H34"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
join_time | int | Date of employment.<br>**Example value**: 2147483647<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
employee_no | string | Employee ID.<br>**Example value**: "1"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
employee_type | int | Employee type. Optional values are:<br>- 1: Regular<br>- 2: Intern<br>- 3: Outsourcing<br>- 4: Contractor<br>- 5: Consultant <br>At the same time, the interface can read the int value of the custom employee type. You can call the [Query Employee Type](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/list) interface to get the name of the custom employee type in the current tenant.<br>**Example value**: 1
orders | user_order\[\] | User sorting information. Indicates the order of personnel in the organizational structure. Personnel may exist in multiple departments and have different orders.
&emsp;∟&nbsp;department_id | string | Department ID. For detailed description of department resources, please refer to [Department Resource Introduction](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#23857fe0).<br>**Example value**: "od-4e6ac4d14bcd5071a37a39de902c7141"
&emsp;∟&nbsp;user_order | int | The user's ranking in their direct department. A larger value indicates a higher ranking.<br>**Example value**: 100
&emsp;∟&nbsp;department_order | int | Ranking of the user's departments. A larger value indicates a higher ranking.<br>**Example value**: 100
custom_attrs | user_custom_attr\[\] | Custom field.<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
&emsp;∟&nbsp;type | string | Custom field type.   <br>- TEXT<br>- HREF<br>- ENUMERATION<br>- PICTURE_ENUM<br>- GENERIC_USER<br>**Example value**: "TEXT"
&emsp;∟&nbsp;id | string | Custom field ID.<br>**Example value**: "DemoId"
&emsp;∟&nbsp;value | user_custom_attr_value | Custom field value.
&emsp;&emsp;∟&nbsp;text | string | - When the field type is TEXT, this parameter defines the field value.<br>- When the field type is HREF, this parameter defines the webpage title.<br>**Example value**: "DemoText"
&emsp;&emsp;∟&nbsp;url | string | When the field type is HREF, this parameter defines the default URL.<br>**Example value**: "http://www.feishu.cn"
&emsp;&emsp;∟&nbsp;pc_url | string | When the field type is HREF, this parameter defines URL on the PC.<br>**Example value**: "http://www.feishu.cn"
&emsp;&emsp;∟&nbsp;option_id | string | When the field type is ENUMERATION or PICTURE_ENUM, this parameter defines the option value.<br>**Example value**: "edcvfrtg"
&emsp;&emsp;∟&nbsp;generic_user | custom_attr_generic_user | When the field type is GENERIC_USER, this parameter defines the user referenced.
&emsp;&emsp;&emsp;∟&nbsp;id | string | User's user_id.<br>**Example value**: "9b2fabg5"
&emsp;&emsp;&emsp;∟&nbsp;type | int | User type. Currently only the value 1 is supported, indicating user.<br>**Example value**: 1
enterprise_email | string | Business email. <br>**Notice**: Make sure that Feishu Business Mail has been enabled in Admin.<br>**Example value**: "demo@mail.com"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)
job_title | string | Job title.<br>**Example value**: "xxxxx"<br>**Required field scopes (Satisfy any)**:<br>Obtain user's employment information(contact:user.employee:readonly)<br>Read Contacts as an app(contact:contact:readonly_as_app)

### Data example
```json
{
    "user_id": "u273y71",
    "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "union_id": "ou_be2c1742f2bb189469bdd33f0b1516ea",
    "name": "John",
    "en_name": "San Zhang",
    "email": "zhangsan@gmail.com",
    "mobile": "13011111111",
    "mobile_visible": false,
    "gender": 1,
    "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
    "department_ids": [
        "od-4e6ac4d14bcd5071a37a39de902c7141"
    ],
    "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "city": "Hangzhou",
    "country": "CN",
    "work_station": "North building-H34",
    "join_time": 2147483647,
    "employee_no": "1",
    "employee_type": 1,
    "orders": [
        {
            "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
            "user_order": 100,
            "department_order": 100
        }
    ],
    "custom_attrs": [
        {
            "type": "TEXT",
            "id": "DemoId",
            "value": {
                "text": "DemoText",
                "url": "http://www.feishu.cn",
                "pc_url": "http://www.feishu.cn",
                "option_id": "edcvfrtg",
                "generic_user": {
                    "id": "9b2fabg5",
                    "type": 1
                }
            }
        }
    ],
    "enterprise_email": "demo@mail.com",
    "job_title": "xxxxx"
}
```
