# Search for movement information

Search for movement information

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/corehr/v2/job_changes/search
HTTP Method | POST
Rate Limit | [100 per minute](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.**<br>Enable any scope from the list | Get job status change information(corehr:job_change:read)<br>Update employee's job status change information(corehr:job_change:write)
Required field scopes | **Notice**：The response body of the API contains the following sensitive fields, and they will be returned only after corresponding scopes are added. If you do not need the fields, it is not recommended that you request the scopes.<br>Get information of contracting parties(corehr:contract.company:read)<br>Get employee's employment contract period(corehr:contract.period:read)<br>Get employee's job information(corehr:employment.job:read)<br>Get employee's job level(corehr:employment.job_level:read)<br>获取员工异动自定义字段信息(corehr:job_change.custom_field:read)<br>View custom field in job status change information(corehr:job_change.employment_custom_field:read)<br>Get remark field in job status change process(corehr:job_change.remark:read)<br>Read and write job grade information(corehr:employment.job_grade:write)<br>Obtain user ID(contact:user.employee_id:readonly)<br>Read and write employee's job level information(corehr:employment.job_level:write)<br>Read and write employee's employment contract period(corehr:contract.period:write)<br>Read and write information of contracting parties(corehr:contract.company:write)<br>获取异动单据是否调薪字段(corehr:job_change.is_adjust_salary:read)<br>Get job grade information(corehr:employment.job_grade:read)<br>获取异动单据社保字段(corehr:job_change.social_security_city:read)<br>Get salary type(corehr:job_data.compensation_type:read)<br>Get company of employment(corehr:job_data.service_company:read)

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
page_size | int | Yes | Page size, up to 100<br>**Example value**: 100<br>**Data validation rules**:<br>- Value range: `1` ～ `100`
page_token | string | No | Page identifier. It is not filled in the first request, indicating traversal from the beginning; when there will be more groups, the new page_token will be returned at the same time, and the next traversal can use the page_token to get more groups<br>**Example value**: 6891251722631890445
user_id_type | string | No | User ID categories<br>**Example value**: open_id<br>**Optional values are**:<br>- open_id：Identifies a user to an app. The same user has different Open IDs in different apps. [How to get Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：Identifies a user to a tenant that acts as a developer. A user has the same Union ID in apps developed by the same developer, and has different Union IDs in apps developed by different developers. A developer can use Union ID to link the same user's identities in multiple apps.[How to get Union ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：Identifies a user to a tenant. The same user has different User IDs in different tenants. In one single tenant, a user has the same User ID in all apps （including store apps）. User ID is usually used to communicate user data between different apps. [How to get User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br><md-enum-item key="people_corehr_id" ><br>**Default value**: `open_id`<br>**When the value is `user_id`, the following field scopes are required**:<br>Obtain user ID(contact:user.employee_id:readonly)
department_id_type | string | No | The department ID type used in this call<br>**Example value**: open_department_id<br>**Optional values are**:<br>- open_department_id：Identify departments by open_department_id<br>- department_id：Identify departments by department_id<br>- people_corehr_department_id：Identify departments by people_corehr_department_id<br>**Default value**: `open_department_id`

### Request body

Parameter | Type | Required | Description
---|---|---|---
employment_ids | string\[\] | No | Employee ID list<br>**Example value**: ["ou_a294793e8fa21529f2a60e3e9de45520"]<br>**Data validation rules**:<br>- Maximum length: `30`
job_change_ids | string\[\] | No | Transaction record ID list<br>**Example value**: ["7044427347159746085"]<br>**Data validation rules**:<br>- Maximum length: `10`
statuses | string\[\] | No | Transaction state, the relationship between multiple states is "or"<br>**Example value**: ["Approving"]<br>**Optional values are**:<br>- Approving：Approving approval<br>- Approved：Approved<br>- Transformed：Transformed<br>- Rejected：Rejected rejected<br>- Cancelled：Cancelled Cancelled<br>- NoNeedApproval：NoNeedApproval No approval required<br>**Data validation rules**:<br>- Maximum length: `10`
effective_date_start | string | No | Effective date of the change - the start of the search range, which needs to be used together with the end of the search range<br>**Example value**: "2022-01-01"
effective_date_end | string | No | Effective date of the change - search range ends<br>**Example value**: "2022-01-01"
updated_time_start | string | No | Updated time of the change - the start of the search range, which needs to be used together with the end of the search range. Millisecond timestamp<br>**Example value**: "1704084635000"
updated_time_end | string | No | Updated time of the change - search range ends. Millisecond timestamp<br>**Example value**: "1704084635000"
target_department_ids | string\[\] | No | List of new department IDs<br>**Example value**: ["7269981744640312876"]<br>**Data validation rules**:<br>- Maximum length: `30`
transfer_type_unique_identifier | string\[\] | No | transfer type list<br>**Example value**: ["assignment_start_reason_option5"]<br>**Data validation rules**:<br>- Maximum length: `30`
transfer_reason_unique_identifier | string\[\] | No | transfer reason list<br>**Example value**: ["reason_for_job_change_option_7182520625066475540_7382109467556446228"]<br>**Data validation rules**:<br>- Maximum length: `30`
exception_statuses | string\[\] | No | exception status list<br>**Example value**: ["pending"]<br>**Optional values are**:<br>- pending：pending<br>- processed：processed<br>**Data validation rules**:<br>- Maximum length: `10`

### Request body example
```json
{
    "employment_ids": [
        "ou_a294793e8fa21529f2a60e3e9de45520"
    ],
    "job_change_ids": [
        "7044427347159746085"
    ],
    "statuses": [
        "Approving"
    ],
    "effective_date_start": "2022-01-01",
    "effective_date_end": "2022-01-01",
    "updated_time_start": "1704084635000",
    "updated_time_end": "1704084635000",
    "target_department_ids": [
        "7269981744640312876"
    ],
    "transfer_type_unique_identifier": [
        "assignment_start_reason_option5"
    ],
    "transfer_reason_unique_identifier": [
        "reason_for_job_change_option_7182520625066475540_7382109467556446228"
    ],
    "exception_statuses": [
        "pending"
    ]
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
items | job_change\[\] | Employee Movement List
job_change_id | string | Transaction record id
employment_id | string | Employee ID
status | string | Transaction state<br>**Optional values are**:<br>- Approving：Approval is in progress.<br>- Approved：Approved<br>- Transformed：Has changed<br>- Rejected：Rejected<br>- Cancelled：Revoked<br>- NoNeedApproval：No approval required
transfer_type_unique_identifier | string | Transaction type
transfer_reason_unique_identifier | string | Cause of change
process_id | string | Transaction process id
effective_date | string | Effective time
created_time | string | Creation time
updated_time | string | Update time
transfer_info | transfer_info | Transaction Details
remark | string | Remarks<br>**Required field scopes**:<br>Get remark field in job status change process(corehr:job_change.remark:read)
offer_info | string | Offer information
target_dotted_manager_clean | boolean | Whether to undo dotted-line manager
probation_exist | boolean | Is there a probation period
original_department | string | original department
target_department | string | New department
target_draft_department | string | New department, before the approval of the new department is completed, it will return the temporary ID td_xxx
original_department_id_path | orgdraft_department_id\[\] | The full path of the original department
department_id | string | Department ID, it will return a null value before the approval of the new department
draft_department_id | string | The ID of the adjusted department, a temporary ID in the format of td_xxx will be returned before the approval of the new department
target_department_id_path | orgdraft_department_id\[\] | The full path of the new department
department_id | string | Department ID, it will return a null value before the approval of the new department
draft_department_id | string | The ID of the adjusted department, a temporary ID in the format of td_xxx will be returned before the approval of the new department
original_work_location | string | Original work place
target_work_location | string | New duty station
original_direct_manager | string | Former direct manager
target_direct_manager | string | New direct manager
original_dotted_manager | string | Former dotted-line manager
target_dotted_manager | string | New dotted-line manager
original_job | string | Former position<br>**Required field scopes (Satisfy any)**:<br>Get employee's job information(corehr:employment.job:read)<br>Get employee's job level(corehr:employment.job_level:read)<br>Read and write employee's job level information(corehr:employment.job_level:write)
target_job | string | New job<br>**Required field scopes (Satisfy any)**:<br>Get employee's job information(corehr:employment.job:read)<br>Get employee's job level(corehr:employment.job_level:read)<br>Read and write employee's job level information(corehr:employment.job_level:write)
original_job_family | string | Original sequence
target_job_family | string | New sequence
original_job_level | string | Original level<br>**Required field scopes (Satisfy any)**:<br>Get employee's job level(corehr:employment.job_level:read)<br>Read and write employee's job level information(corehr:employment.job_level:write)
target_job_level | string | New level<br>**Required field scopes (Satisfy any)**:<br>Get employee's job level(corehr:employment.job_level:read)<br>Read and write employee's job level information(corehr:employment.job_level:write)
original_workforce_type | string | Original personnel type
target_workforce_type | string | New personnel type
original_employee_subtype | string | &nbsp;
target_employee_subtype | string | &nbsp;
original_company | string | Original company<br>**Required field scopes (Satisfy any)**:<br>Get information of contracting parties(corehr:contract.company:read)<br>Read and write information of contracting parties(corehr:contract.company:write)
target_company | string | New company<br>**Required field scopes (Satisfy any)**:<br>Get information of contracting parties(corehr:contract.company:read)<br>Read and write information of contracting parties(corehr:contract.company:write)
original_contract_number | string | Original contract number
target_contract_number | string | New contract number
original_contract_type | string | Original contract type
target_contract_type | string | New contract type
original_duration_type | string | Original Term Type
target_duration_type | string | New Term Type
original_signing_type | string | Original signing type
target_signing_type | string | New signing type
original_contract_start_date | string | Original contract start date<br>**Required field scopes (Satisfy any)**:<br>Get employee's employment contract period(corehr:contract.period:read)<br>Read and write employee's employment contract period(corehr:contract.period:write)
target_contract_start_date | string | New contract start date<br>**Required field scopes (Satisfy any)**:<br>Get employee's employment contract period(corehr:contract.period:read)<br>Read and write employee's employment contract period(corehr:contract.period:write)
original_contract_end_date | string | Original contract end date<br>**Required field scopes (Satisfy any)**:<br>Get employee's employment contract period(corehr:contract.period:read)<br>Read and write employee's employment contract period(corehr:contract.period:write)
target_contract_end_date | string | New contract end date<br>**Required field scopes (Satisfy any)**:<br>Get employee's employment contract period(corehr:contract.period:read)<br>Read and write employee's employment contract period(corehr:contract.period:write)
original_working_hours_type | string | Original working hour system
target_working_hours_type | string | New working hour system
original_working_calendar | string | Original work calendar
target_working_calendar | string | New work calendar
original_probation_end_date | string | Expected end date of original probation period
target_probation_end_date | string | Expected end date of new probation period
original_weekly_working_hours | string | Working hours per week
target_weekly_working_hours | string | New week working hours
original_work_shift | string | Original schedule
target_work_shift | string | New schedule
original_cost_center_rate | job_data_cost_center\[\] | Original cost center allocation method
cost_center_id | string | Cost center ID, you can obtain the corresponding cost center information through the [Query single cost center information] interface
rate | int | Apportionment ratio
target_cost_center_rate | job_data_cost_center\[\] | New cost center allocation method
cost_center_id | string | Cost center ID, you can obtain the corresponding cost center information through the [Query single cost center information] interface
rate | int | Apportionment ratio
original_employment_change | tranfer_employment_info | Original job information
regular_employee_start_date | string | Date of transfer to regular employee
seniority_date | string | Tenure start date
employee_number | string | Employee ID
custom_fields | custom_field_data\[\] | custom field<br>**Required field scopes**:<br>View custom field in job status change information(corehr:job_change.employment_custom_field:read)
custom_api_name | string | Custom field apiname, which is the unique identifier of the custom field
name | custom_name | Custom field name
zh_cn | string | Chinese
en_us | string | English
type | int | Custom field type
value | string | Field value, is the string escaped by json, according to the metadata definition, the field format is different (such as 123, 123.23, "true", ["id1", "id2"], "2006-01-02 15:04:05")
target_employment_change | tranfer_employment_info | New job information
regular_employee_start_date | string | Date of transfer to regular employee
seniority_date | string | Tenure start date
employee_number | string | Employee ID
custom_fields | custom_field_data\[\] | custom field<br>**Required field scopes**:<br>View custom field in job status change information(corehr:job_change.employment_custom_field:read)
custom_api_name | string | Custom field apiname, which is the unique identifier of the custom field
name | custom_name | Custom field name
zh_cn | string | Chinese
en_us | string | English
type | int | Custom field type
value | string | Field value, is the string escaped by json, according to the metadata definition, the field format is different (such as 123, 123.23, "true", ["id1", "id2"], "2006-01-02 15:04:05")
original_job_grade | string | Original job grade<br>**Required field scopes (Satisfy any)**:<br>Get job grade information(corehr:employment.job_grade:read)<br>Read and write job grade information(corehr:employment.job_grade:write)
target_job_grade | string | Target job grade<br>**Required field scopes (Satisfy any)**:<br>Get job grade information(corehr:employment.job_grade:read)<br>Read and write job grade information(corehr:employment.job_grade:write)
original_compensation_type | string | Original service company<br>**Required field scopes**:<br>Get salary type(corehr:job_data.compensation_type:read)
target_compensation_type | string | Target service company<br>**Required field scopes**:<br>Get salary type(corehr:job_data.compensation_type:read)
original_service_company | string | **Required field scopes**:<br>Get company of employment(corehr:job_data.service_company:read)
target_service_company | string | **Required field scopes**:<br>Get company of employment(corehr:job_data.service_company:read)
original_position | string | The original position can be obtained through the relevant API of [Post Job Management - Post] (currently only some tenants are grey released, if necessary, please contact the administrator to open gray)
target_position | string | New positions can be obtained through the relevant API of [Post Job Management - Post] (currently only some tenants are grey released, if necessary, please contact the administrator to open gray)
target_draft_position | string | &nbsp;
original_social_security_city | string | **Required field scopes**:<br>获取异动单据社保字段(corehr:job_change.social_security_city:read)
target_social_security_city | string | **Required field scopes**:<br>获取异动单据社保字段(corehr:job_change.social_security_city:read)
is_transfer_with_workforce | boolean | &nbsp;
is_adjust_salary | boolean | **Required field scopes**:<br>获取异动单据是否调薪字段(corehr:job_change.is_adjust_salary:read)
custom_fields | custom_field_data\[\] | **Required field scopes**:<br>获取员工异动自定义字段信息(corehr:job_change.custom_field:read)
custom_api_name | string | &nbsp;
name | custom_name | &nbsp;
zh_cn | string | chinese name
en_us | string | english name
type | int | Custom field type
value | string | Custom field value
has_more | boolean | Whether the response body has more parameters
page_token | string | Page identifier, when has_more is true, a new page_token will also be returned. Otherwise, page_token will not be returned

### Response body example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "job_change_id": "6991776076699549697",
                "employment_id": "ou_a294793e8fa21529f2a60e3e9de45520",
                "status": "Approved",
                "transfer_type_unique_identifier": "direct_leader_change",
                "transfer_reason_unique_identifier": "involuntary_transfer",
                "process_id": "6991776078461142564",
                "effective_date": "2022-03-01",
                "created_time": "1627899724000",
                "updated_time": "1647434443000",
                "transfer_info": {
                    "remark": "异动详情",
                    "offer_info": "优质人才，加急处理",
                    "target_dotted_manager_clean": true,
                    "probation_exist": false,
                    "original_department": "6966236933198579208",
                    "target_department": "6966236933198579208",
                    "target_draft_department": "6966236933198579208",
                    "original_department_id_path": [
                        {
                            "department_id": "6974659700705068581",
                            "draft_department_id": "6974659700705068581"
                        }
                    ],
                    "target_department_id_path": [
                        {
                            "department_id": "6974659700705068581",
                            "draft_department_id": "6974659700705068581"
                        }
                    ],
                    "original_work_location": "6967271100992587295",
                    "target_work_location": "6967271100992587295",
                    "original_direct_manager": "6974641477444060708",
                    "target_direct_manager": "7013619729281713671",
                    "original_dotted_manager": "6974648866876573198",
                    "target_dotted_manager": "7013328578351842852",
                    "original_job": "6969469398088287751",
                    "target_job": "6969469557836760606",
                    "original_job_family": "6967287547462419975",
                    "target_job_family": "6967287547462419975",
                    "original_job_level": "6972085707674355214",
                    "target_job_level": "6972085707674355214",
                    "original_workforce_type": "6968386026792289828",
                    "target_workforce_type": "7036268995372303885",
                    "original_employee_subtype": "6968386026792289828",
                    "target_employee_subtype": "7036268995372303885",
                    "original_company": "6974659700705068581",
                    "target_company": "6974659700705068581",
                    "original_contract_number": "55332",
                    "target_contract_number": "55333",
                    "original_contract_type": "labor_contract",
                    "target_contract_type": "labor_contract",
                    "original_duration_type": "fixed_term",
                    "target_duration_type": "fixed_term",
                    "original_signing_type": "new",
                    "target_signing_type": "new",
                    "original_contract_start_date": "2021-07-01",
                    "target_contract_start_date": "2021-07-01",
                    "original_contract_end_date": "2024-07-01",
                    "target_contract_end_date": "2024-07-01",
                    "original_working_hours_type": "6969087376740206087",
                    "target_working_hours_type": "6969087376740206087",
                    "original_working_calendar": "6969087376740236087",
                    "target_working_calendar": "6969087376740236087",
                    "original_probation_end_date": "2021-11-17",
                    "target_probation_end_date": "2021-11-17",
                    "original_weekly_working_hours": "162",
                    "target_weekly_working_hours": "160",
                    "original_work_shift": "work_shift",
                    "target_work_shift": "non_work_shift",
                    "original_cost_center_rate": [
                        {
                            "cost_center_id": "6950635856373745165",
                            "rate": 100
                        }
                    ],
                    "target_cost_center_rate": [
                        {
                            "cost_center_id": "6950635856373745165",
                            "rate": 100
                        }
                    ],
                    "original_employment_change": {
                        "regular_employee_start_date": "2023-01-01",
                        "seniority_date": "2023-01-01",
                        "employee_number": "1111111",
                        "custom_fields": [
                            {
                                "custom_api_name": "name",
                                "name": {
                                    "zh_cn": "custom name",
                                    "en_us": "Custom Name"
                                },
                                "type": 1,
                                "value": "231"
                            }
                        ]
                    },
                    "target_employment_change": {
                        "regular_employee_start_date": "2023-01-01",
                        "seniority_date": "2023-01-01",
                        "employee_number": "1111111",
                        "custom_fields": [
                            {
                                "custom_api_name": "name",
                                "name": {
                                    "zh_cn": "custom name",
                                    "en_us": "Custom Name"
                                },
                                "type": 1,
                                "value": "231"
                            }
                        ]
                    },
                    "original_job_grade": "7289005963599693366",
                    "target_job_grade": "7289005963599693366",
                    "original_compensation_type": "hourly",
                    "target_compensation_type": "salary",
                    "original_service_company": "7289005963599693367",
                    "target_service_company": "7289005963599693367",
                    "original_position": "7289005963599693367",
                    "target_position": "7289005963599693367",
                    "target_draft_position": "7289005963599693367",
                    "original_social_security_city": "7289005963599693367",
                    "target_social_security_city": "7289005963599693367",
                    "is_transfer_with_workforce": false
                },
                "is_adjust_salary": true,
                "custom_fields": [
                    {
                        "custom_api_name": "name",
                        "name": {
                            "zh_cn": "自定义姓名",
                            "en_us": "Custom Name"
                        },
                        "type": 1,
                        "value": "\"231\""
                    }
                ]
            }
        ],
        "has_more": true,
        "page_token": "6891251722631890445"
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
500 | 1160101 | marshal error | please oncall, https://applink.feishu.cn/TLJpeNdW
500 | 1160102 | unmarshal error | please oncall, https://applink.feishu.cn/TLJpeNdW
500 | 1160103 | request ID repeat | Change the request id
500 | 1160104 | custom field format error | please oncall, https://applink.feishu.cn/TLJpeNdW
500 | 1160105 | field is required | Please check the parameters
500 | 1160106 | date format should be 2006-01-02 | Please check the date parameters
400 | 1160107 | param is invalid | Please check the parameters

