# Sync instances

The Approval Center does not handle the circulation of approvals; the circulation of approvals occurs within the third-party system. This interface is used to synchronize the approval instances, approval tasks, and approval forwarding data generated in the third-party system after the approval circulation to the Approval Center.

## Implementation effects

After calling this interface to synchronize third-party approval instances, enterprise employees can browse synchronized approval instances, tasks, and forwarded information in the Approval Center and jump back to the third-party system to view and operate approvals. Approval instance information will be listed under **Submitted** in the Approval Center, task information under **To-do** and **Done** lists, and forwarded information under **CC'd** list.

If the third-party approval callback URL is set when [creating a third-party approval definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/external_approval/create), you can configure [third-party quick approval callback](https://open.feishu.cn/document/ukTMukTMukTM/ukjNyYjL5YjM24SO2IjN/quick-approval-callback) for approval tasks. This allows the approver to operate approvals directly within the Approval Center. The Approval Center will then send the approval result back to the third-party system, which updates the task information upon receiving the callback and synchronizes the updated task information back to the Approval Center, thus forming a closed loop.

## Notes

Ensure the uniqueness of various entity IDs (instance, task, forwarding) within the approval instance. IDs should not be duplicated between different entities. If instance IDs, task IDs, or forwarding IDs are duplicated, it will result in missing corresponding approval data in the Approval Center.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/approval/v4/external_instances
HTTP Method | POST
Rate Limit | [1000 per minute & 50 per second](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 | View, create, update, and delete info of Approval app(approval:approval)<br>View, create, update, and delete info in third-party approval instance(approval:external_instance)

### 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"

### Request body

Parameter | Type | Required | Description
---|---|---|---
approval_code | string | Yes | Approval Definition Code. The return value from [creating a third-party approval definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/external_approval/create) is used to specify the approval definition to which the current instance belongs.<br>**Note**: If the `title` parameter is set in the current interface, the approval instance name is displayed according to the `title`. If `title` is not set, the title of the approval instance is taken from the `name` parameter of the corresponding approval definition (`approval_code`).<br>**Example value**: "81D31358-93AF-92D6-7425-01A5D67C4E71"
status | string | Yes | Approval instance status<br>**Example value**: "PENDING"<br>**Optional values are**:<br>- PENDING：Approving<br>- APPROVED：The approval process has ended, and the result is approval.<br>- REJECTED：The approval process has ended, and the result is rejection.<br>- CANCELED：Approval sponsor withdraws<br>- DELETED：Approval deleted<br>- HIDDEN：Status hide (do not show status)<br>- TERMINATED：Approval terminated
extra | string | No | Approval instance extension parameter, JSON format, needs to be compressed and escaped into a string when passing the value. The document number is realized by passing the business_key parameter.<br>**Note**: The following example values ​​are not escaped, please pay attention to escape when using. You can view the escaped extra example value in the request body example.<br>**Example value**: "{\"xxx\":\"xxx\",\"business_key\":\"xxx\"}"
instance_id | string | Yes | The approval instance is uniquely identified, user-defined, and it is necessary to ensure that the certificate tenant and the application are unique.<br>**Example value**: "24492654"
links | external_instance_link | Yes | Approval instance link information. The set link is used to click in the **Initiated** list of the approval center to jump back to the third-party approval system to view the approval details.
pc_link | string | Yes | The PC-side third-party approval instance jump link.<br>**Description**:<br>- When users use the Feishu PC side to view instance details, they will jump through this link.<br>- At least one of pc_link and mobile_link must be filled in.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
mobile_link | string | No | The mobile version of the third-party approval instance jump link.<br>**Description**:<br>- When users use the Feishu mobile version to view instance details, they will be redirected through this link.<br>- At least one of pc_link and mobile_link must be filled in.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
title | string | No | Approval display name.<br>**Description**:<br>- If this parameter is filled in, the approval name in the approval list uses this parameter. If this parameter is not filled in, the approval name uses the name defined by the approval.<br>- The internationalized text Key (i.e. the Key in the i18n_resources.texts parameter) is passed in here, and the value needs to be assigned in the i18n_resources.texts parameter in the Key:Value format.<br>- The Key needs to start with @i18n@.<br>**Example value**: "@i18n@1"
form | external_instance_form\[\] | No | The form data filled in by the user when submitting for approval is used for display in all approval lists. Multiple values can be submitted, but only the first 3 will be displayed in the approval center, and the total length should not exceed 2048 characters.<br>**Example value**: [{ "name": "@i18n@2", "value": "@i18n@3" }]
name | string | No | The form field name.<br>**Note**:<br>- The internationalized text key (i.e. the key in the i18n_resources.texts parameter) is passed in here, and the value needs to be assigned in the i18n_resources.texts parameter in the Key:Value format.<br>- The key needs to start with @i18n@.<br>**Example value**: "@i18n@2"
value | string | No | Form Value.<br>**Note**:<br>- The value passed here is the key for internationalization texts (i.e., the Key from the `i18n_resources.texts` parameter), which also needs to be assigned in the `i18n_resources.texts` parameter in a Key:Value format.<br>- The Key should start with `@i18n@`.<br>**Example value**: "@i18n@3"
user_id | string | No | Approval Initiator user_id. The initiator can see all initiated approvals in the "Initiated" list in the Approval Center. In the "Pending", "Completed", and "CC" lists, this field is used to display the initiator of the approval. For the method to obtain the user ID, see [How to Obtain User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id).<br>**Note**: At least one of the initiator's `open_id` or `user_id` must be provided.<br>**Example value**: "A987sf9s"
user_name | string | No | Username of the approval initiator. If the initiator is not a real user (e.g., a department), and does not have a `user_id`, this parameter can be used to pass in a name.<br>**Note**:<br>- The value passed here is the key for internationalization texts (i.e., the Key from the `i18n_resources.texts` parameter), which also needs to be assigned in the `i18n_resources.texts` parameter in a Key:Value format.<br>- The Key should start with `@i18n@`.<br>**Example value**: "@i18n@9"
open_id | string | No | Approval Initiator open_id. The initiator can see all initiated approvals in the "Initiated" list in the Approval Center. In the "Pending", "Completed", and "CC" lists, this field is used to display the initiator of the approval. For the method to obtain the open ID, see [How to Obtain Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid).<br>**Note**: At least one of the initiator's `open_id` or `user_id` must be provided.<br>**Example value**: "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1"
department_id | string | No | Department ID of the initiator, which is used to display the department of the initiator in the Approval Center list. If the value is not provided, it will not be displayed. For the method to obtain the department ID, see [Department ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#9c02ed7a).<br>**Note**: If the user has not joined any department, pass an empty string `""`, and it will default to displaying the company name. If the `department_name` parameter is provided, the corresponding department name will be displayed.<br>**Example value**: "OD-8EC33278BC2"
department_name | string | No | Department name of the approval initiator. If the initiator is not a real user or does not belong to a department, this parameter can be used to pass in the department name.<br>**Note**:<br>- The value passed here is the key for internationalization texts (i.e., the Key from the `i18n_resources.texts` parameter), which also needs to be assigned in the `i18n_resources.texts` parameter in a Key:Value format.<br>- The Key should start with `@i18n@`.<br>**Example value**: "@i18n@10"
start_time | string | Yes | Approval initiation time, Unix millisecond timestamp<br>**Example value**: "1556468012678"
end_time | string | Yes | Approval instance end time: 0 for unfinished approvals, Unix millisecond timestamp<br>**Example value**: "1556468012678"
update_time | string | Yes | The latest update time of the approval instance, unix millisecond timestamp, used for data version control in push operations. If the `update_mode` value is set to `UPDATE`, the approval instance information in the Approval Center will only be updated when the provided `update_time` has changed (i.e., is greater than the previous value).<br>**Note**: This parameter is mainly used to prevent old data from updating new data during concurrent operations.<br>**Example value**: "1556468012678"
display_method | string | No | How to open an approval instance on the list page<br>**Example value**: "BROWSER"<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open with hosting (i.e., hosting in the Feishu Approval Center)
update_mode | string | No | Update mode.<br>- When `update_mode` is set to `REPLACE`, the current pushed data will always be used as the final data, and any extra tasks or copied data in the Approval Center that are not included in this push will be deleted.<br>- When `update_mode` is set to `UPDATE`, the data in the Approval Center will not be deleted, but only new instances and task data will be added or updated.<br>**Default value**: `REPLACE`<br>**Example value**: "UPDATE"<br>**Optional values are**:<br>- REPLACE：Full replacement, default<br>- UPDATE：incremental update
task_list | external_instance_task_node\[\] | No | Task list<br>**Data validation rules**:<br>- Maximum length: `300`
task_id | string | Yes | Unique identifier within the approval instance to locate data when updating the approval task<br>**Example value**: "112534"
user_id | string | No | Approver's user_id, the method to obtain it can be found in [How to Obtain User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id).<br>**Notes**:<br>- This task will appear in the **Pending** or **Completed** list in the approver's Feishu Approval Center.<br>- At least one of `user_id` or `open_id` must be provided.<br>**Example value**: "A987sf9s"
open_id | string | No | Approver's open_id, the method to obtain it can be found in [How to Obtain Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid).<br>**Notes**:<br>- This task will appear in the **Pending** or **Completed** list in the approver's Feishu Approval Center.<br>- At least one of `user_id` or `open_id` must be provided.<br>**Example value**: "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1"
title | string | No | Approval task name.<br>**Notes**:<br>- The value passed here is an internationalization document key (i.e., the key in `i18n_resources.texts` parameter), and the key needs to be assigned in `i18n_resources.texts` parameter in Key:Value format.<br>- The key must start with `@i18n@`.<br>**Example value**: "i18n1"
links | external_instance_link | Yes | A third-party approval redirection link used in the Approval Center's **To-do** and **Done** sections, which allows users to return to the third-party approval system to view task details.
pc_link | string | Yes | PC-side redirection link.<br>**Notes**:<br>- When the user views task details on the Feishu PC side, this link will be used for redirection.<br>- At least one of `pc_link` or `mobile_link` must be provided.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
mobile_link | string | No | Mobile-side redirection link.<br>**Notes**:<br>- When the user views task details on the Feishu mobile side, this link will be used for redirection.<br>- At least one of `pc_link` or `mobile_link` must be provided.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
status | string | Yes | Task status<br>**Example value**: "PENDING"<br>**Optional values are**:<br>- PENDING：Pending approval<br>- APPROVED：Task agreed<br>- REJECTED：Task denied<br>- TRANSFERRED：Task transfer<br>- DONE：The task passed but the approver did not operate it; the approver cannot see the task. If you want to see it, you can copy the person.
extra | string | No | Extend json, the reason for the end of the task needs to be passed complete_reason field. The enumeration value and the corresponding description:<br>- approved: agreed<br>- rejected: rejected<br>- node_auto_reject: Automatic rejection (due to logical judgment)<br>- specific_rollback: return (including return to the sponsor, return to any intermediate approver)<br>- add: and sign (add a new approver, approve with me)<br>- add_pre: Pre-approver (add new approver, approve before me)<br>- add_post: post-approver (add new approver, approve after me)<br>- delete_assignee: Reductions<br>- forward: manual transfer<br>- forward_resign: automatic transfer upon resignation<br>- recall: revocation (withdrawal of documents, invalidation of documents)<br>- delete: delete the approval slip<br>- admin_forward: the administrator operates the forwarding in the background<br>- system_forward: the system automatically transfers<br>- auto_skip: Auto Pass<br>- manual_skip: manually skip<br>- submit_again: resubmit tasks<br>- restart: restart the process<br>- others: others (as a backstop)<br>**Example value**: "{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}"
create_time | string | Yes | Task creation time, Unix millisecond timestamp<br>**Example value**: "1556468012678"
end_time | string | Yes | Task completion time: 0 for unfinished approvals, Unix millisecond timestamp<br>**Example value**: "1556468012678"
update_time | string | No | The last update time of the task, unix millisecond timestamp, which is used to push data versioning; update the policy update_time in the same instance<br>**Example value**: "1556468012678"
action_context | string | No | Operation context, when the user operates, this parameter is included in the callback request to pass the context data of the task<br>**Example value**: "123456"
action_configs | action_config\[\] | No | Quick action configuration at the task level.<br>**Note**: Shortcut keys are currently only supported on the Feishu mobile side.
action_type | string | Yes | Operation type, each task can be configured with 2 operations, which will be displayed in the approval list. When the user operates, the callback request will bring this field, indicating whether the user has agreed to the operation or refused the operation<br>** Optional values are **:<br>< Md-enum ><br>< md-enum-item key = "APPROVE" > Agree </md-enum-item ><br>< md-enum-item key = "REJECT" > Deny </md-enum-item ><br>< Md-enum-item key = "{KEY}" > Any string, if any string is used, you need to provide action_name </md-enum-item ><br></Md-enum ><br>**Example value**: "APPROVE"
action_name | string | No | Action name. If `action_type` is not equal to `APPROVAL` or `REJECT`, this field must be provided to display the specific action name.<br>**Notes**:<br>- The value passed here is an internationalization text Key (i.e., the Key in the `i18n_resources.texts` parameter), which needs to be assigned in the `i18n_resources.texts` parameter in a Key:Value format.<br>- The Key must start with `@i18n@`.<br>**Example value**: "@i18n@5"
is_need_reason | boolean | No | Whether approval comments are required. When the value is `true`, after the approver operates on the task in the Approval Center, they will need to provide approval comments.<br>**Example value**: false
is_reason_required | boolean | No | Approval comment is required<br>**Example value**: false
is_need_attachment | boolean | No | Opinion whether to support uploading attachments<br>**Example value**: false
display_method | string | No | How to open approval tasks on the list page<br>**Example value**: "BROWSER"<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open in hosted mode
exclude_statistics | boolean | No | Tripartite mission support is not included in efficiency statistics.<br>- false: Include efficiency statistics.<br>- true: efficiency statistics are not included<br>**Example value**: false<br>**Default value**: `false`
node_id | string | No | Approval node ID. It must meet the following conditions:<br>- Within an approval process, each node ID must be unique. For example, in a process, the node IDs for direct superior, senior superior, etc., must be different.<br>- Within the same third-party approval definition, the node ID should remain consistent across different approval instances for the same nodes. For example, if User A and User B both initiate leave requests, the node ID for the direct superior node should be consistent in both approval instances.<br>**Example value**: "Node"
node_name | string | No | Node name.<br>**Notes**:<br>- The value passed here is an internationalization text Key (i.e., the Key in the `i18n_resources.texts` parameter), which needs to be assigned in the `i18n_resources.texts` parameter in a Key:Value format.<br>- The Key must start with `@i18n@`.<br>**Example value**: "i18n@name"
generate_type | string | No | task generation type, can be left blank, but do not fill in the blank string.<br>**Example value**: "EXTERNAL_CONSIGN"<br>**Optional values are**:<br>- EXTERNAL_CONSIGN：Give the agent a completed task<br>- DEFAULT：Default task generated by system
cc_list | cc_node\[\] | No | CC list<br>**Data validation rules**:<br>- Maximum length: `200`
cc_id | string | Yes | Unique identity within the approval instance<br>**Example value**: "123456"
user_id | string | No | CC recipient's `user_id`. For the method of obtaining, please refer to [How to get a user's User ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id).<br>**Note**: At least one of the CC recipient's `open_id` and `user_id` must be provided.<br>**Example value**: "12345"
open_id | string | No | CC recipient's `open_id`. For the method of obtaining, please refer to [How to get a user's Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid).<br>**Note**: At least one of the CC recipient's `open_id` and `user_id` must be provided.<br>**Example value**: "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1"
links | external_instance_link | Yes | Approval CC redirection link. The configured link is used to redirect when clicking within the **CC'd** list in the approval center, taking you back to the third-party approval system to view approval CC details.
pc_link | string | Yes | The jump link on the pc side, when the user uses the Feishu pc side, use this field to jump<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
mobile_link | string | No | Third-party approval instance redirection link for mobile.<br>**Note**:<br>- When users view approval CC on Feishu mobile, this field is used for redirection.<br>- At least one of `pc_link` and `mobile_link` must be provided.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
read_status | string | Yes | Read status<br>**Example value**: "READ"<br>**Optional values are**:<br>- READ：read<br>- UNREAD：unread
extra | string | No | Extended fields. Use JSON format, and the values need to be compressed and escaped into a string when transmitting.<br>**Example value**: "{\"xxx\":\"xxx\"}"
title | string | No | CC task name<br>**Example value**: "XXX"
create_time | string | Yes | CC initiation time, Unix millisecond timestamp<br>**Example value**: "1556468012678"
update_time | string | Yes | CC latest update time, unix millisecond timestamp, used for pushing data versions. If the `update_mode` value is `UPDATE`, the approval instance information in the approval center will only be updated when the transmitted `update_time` changes (increases).<br>**Example value**: "1556468012678"
display_method | string | No | How to open approval tasks on the list page<br>**Example value**: "BROWSER"<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open in hosted mode
i18n_resources | i18n_resource\[\] | Yes | International copywriting
locale | string | Yes | Language<br>**Example value**: "zh-CN"<br>**Optional values are**:<br>- zh-CN：Chinese<br>- en-US：English<br>- ja-JP：Japanese<br>- zh-HK：Traditional Chinese (Hong Kong, China)<br>- zh-TW：Traditional Chinese (Taiwan, China)<br>- de-DE：German<br>- es-ES：Spanish<br>- fr-FR：French<br>- id-ID：Indonesian<br>- it-IT：Italian<br>- ko-KR：Korean<br>- pt-BR：Portuguese<br>- th-TH：Thai<br>- vi-VN：Vietnamese<br>- ms-MY：Malay<br>- ru-RU：Russian
texts | i18n_resource_text\[\] | Yes | Copy Key:Value. Keys need to start with `@i18n@` and pass Values according to the requirements of each parameter. This field is mainly used for internationalization, allowing users to input copies in multiple languages simultaneously. The approval center will use the corresponding copy according to the user's current language environment. If the copy for the user's current language environment is not provided, the default language copy will be used.<br>**Example value**: { "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
key | string | Yes | Copywriting key<br>**Example value**: "@i18n@1"
value | string | Yes | copywriting<br>**Example value**: "People"
is_default | boolean | Yes | Whether the default language, the default language needs to include all keys, non-default language If the key does not exist, the default language will be used instead<br>**Example value**: true
trusteeship_url_token | string | No | Document escrow authentication token, the escrow callback will be accompanied by this token to help the business party authenticate<br>**Example value**: "788981c886b1c28ac29d1e68efd60683d6d90dfce80938ee9453e2a5f3e9e306"
trusteeship_user_id_type | string | No | The type of user, which affects the selection of the user identity field of the request parameter, including the target user returned by the signature operation. Currently only "user_id" is supported<br>**Example value**: "user_id"
trusteeship_urls | trusteeship_urls | No | The URL address of the interface of the document hosting callback access party
form_detail_url | string | No | Get the url address of the data related to the form schema<br>**Example value**: "https://#{your_domain}/api/form_detail"
action_definition_url | string | No | Represents the url address for getting approval action area data<br>**Example value**: "https://#{your_domain}/api/action_definition"
approval_node_url | string | No | Get the url address of the approval record related data<br>**Example value**: "https://#{your_domain}/api/approval_node"
action_callback_url | string | No | The url address of the callback when the approval operation is performed<br>**Example value**: "https://#{your_domain}/api/action_callback"
pull_business_data_url | string | No | Obtain the URL address of the hosted dynamic data. When using this interface, you must ensure that the interface address is synchronized in the data of the historical hosted document. If there is no such interface in the historical document, you need to re-synchronize the data of the historical hosted document to update the URL. This interface is used for the interactive use of the Feishu approval front-end and the line of business. Only the specific components of the approval front-end (the components provided by the Feishu approval front-end and the components that need to interface with the line of business) will be required<br>**Example value**: "https://#{your_domain}/api/pull_business_data"
trusteeship_cache_config | trusteeship_instance_cache_config | No | Managed pre-cache policy
form_policy | string | No | Managed pre-cache policy<br>**Example value**: "DISABLE"<br>**Optional values are**:<br>- DISABLE：Not enabled, default<br>- IMMUTABLE：Forms do not change with the process<br>- BY_NODE：Update cache following process node changes<br>- BY_USER：Store one copy for each to-do task
form_vary_with_locale | boolean | No | Whether the form changes with internationalization<br>**Example value**: false
form_version | string | No | The version number of the currently used form, ensure that after the form is changed, the version number is increased, and the actual value is an int64 integer<br>**Example value**: "1"
resource_region | string | No | The area where the resource is located, the field for internal statistics does not need to be filled in<br>**Example value**: "cn"

### Request body example
```json
{
    "approval_code": "84C18825-A3D2-41D0-891F-E7A2424C5D48",
    "instance_id": "3162634",
    "status": "PENDING",
    "extra": "",
    "links": {
        "pc_link": "http://applink.feishu.cn/sso/common?redirectUrl=/seeyon/main.do?method=main&client=pc",
        "mobile_link": "http://applink.feishu.cn/sso/common?redirectUrl=/seeyon/main.do?method=main&client=pc"
    },
    "title": "@i18n@1",
    "form": [{
        "name": "@i18n@2",
        "value": "@i18n@3"
    }],
    "user_id": "16fb9ff3",
    "user_name": "张三",
    "open_id": "123",
    "department_id": "",
    "department_name": "hr",
    "start_time": "1657093395000",
    "update_time": "1657093395000",
    "end_time": 0,
    "update_mode": "REPLACE",
    "task_list": [{
        "task_id": "112253",
        "user_id": "16fb9ff3",
        "links": {
            "pc_link": "http://",
            "mobile_link": "http://"
        },
        "status": "PENDING",
        "extra": "",
        "title": "agree",
        "create_time": "1638468921000",
        "end_time": 0,
        "update_time": "1638468921000",
        "action_context": "123456",
        "action_configs": [{
            "action_type": "APPROVE",
            "action_name": "@i18n@1",
            "is_need_reason": true,
            "is_reason_required": true,
            "is_need_attachment": true
        }]
    }],
    "cc_list": [{
        "cc_id": "1231243",
        "user_id": "16fb9ff3",
        "open_id": "",
        "links": {
            "pc_link": "http://",
            "mobile_link": "http://"
        },
        "read_status": "READ",
        "extra": "",
        "title": "XXX",
        "create_time": "1657093395000",
        "update_time": "1657093395000"
    }],
    "i18n_resources": [{
        "locale": "zh-CN",
        "is_default": true,
        "texts": [ {"key":"@i18n@1", "value":"test"}, {"key":"@i18n@2", "value":"天"},{"key":"@i18n@3", "value":"2022-07-06"}]
    }]
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
data | external_instance | Synchronized instance data
approval_code | string | Approval definition code
status | string | Approval instance status<br>**Optional values are**:<br>- PENDING：Approving<br>- APPROVED：The approval process is over and the result is consent.<br>- REJECTED：The approval process ends with a rejection<br>- CANCELED：Approval sponsor withdraws<br>- DELETED：Approval deleted<br>- HIDDEN：Status hide (do not show status)<br>- TERMINATED：Approval terminated
extra | string | Approval instance extends JSON. The document number is achieved by passing business_key field
instance_id | string | The approval instance is uniquely identified, user-defined, and it is necessary to ensure that it is unique under the certificate tenant
links | external_instance_link | Approval instance link collection, used for the jump of the [initiated] list, jump back to the three-party system; pc_link and mobile_link must fill in one, which end of the link is filled in, that is, it will jump to the link, not affected by the platform
pc_link | string | The jump link on the pc side, when the user uses the Feishu pc side, use this field to jump
mobile_link | string | Mobile end jump link, when the user uses Feishu mobile end, use this field to jump
title | string | Approval display name.<br>**Note**:<br>- If the `title` parameter is passed in the request, the approval name in the approval list will use the value of that parameter. If the `title` parameter is not provided in the request, the approval name will use the name defined by the approval.<br>- Here, the returned value is the key of the `i18n_resources.texts` parameter. To get the corresponding value, refer to the `i18n_resources.texts.value` returned.
form | external_instance_form\[\] | The form data filled in by the user when submitting for approval is used for display in all approval lists. Multiple values can be passed, but the first 2 are displayed on the PC in the approval center, and the first 3 are displayed on the mobile end, and the length does not exceed 2048 characters
name | string | Form field name. <br>Here, the returned value is the key of the `i18n_resources.texts` parameter. To get the corresponding value, refer to the `i18n_resources.texts.value` returned.
value | string | Form value.<br>Here, the returned value is the key of the `i18n_resources.texts` parameter. To get the corresponding value, refer to the `i18n_resources.texts.value` returned.
user_id | string | Approval sponsor user_id, the sponsor can see all the approvals that have been initiated in the [Initiated] list; in the [Pending Approval], [Approved] [CC Me] list, this field shows who initiated the approval. Approval sponsor open id.
user_name | string | The username of the initiator of the approval process. If the initiator is not a real user (e.g., a department) and does not have a `user_id`, a name can be passed using this parameter.<br>**Note**: The returned value is the key of the `i18n_resources.texts` parameter. To get the corresponding value, refer to the `i18n_resources.texts.value` returned.
open_id | string | Open ID of the approval initiator. The initiator can view all the approvals they have started in the "Initiated" list in the Approval Center. In the "To Do", "Completed", and "CC Me" lists, this field is used to display the initiator of the approval.
department_id | string | The initiator's department ID, used to display the initiator's affiliated department in the Approval Center list. If no value is passed, the department will not be displayed. For information on how to obtain it, refer to [Department ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#9c02ed7a).<br>**Note**: If the user has not joined any department, pass `""`, and the company name will be displayed by default. If the `department_name` parameter is passed, the corresponding department name will be displayed.
department_name | string | The department name of the approval initiator. If the initiator is not a real user or does not belong to a department, a department name can be passed using this parameter.<br>**Note**: The returned value is the key of the `i18n_resources.texts` parameter. To get the corresponding value, refer to the `i18n_resources.texts.value` returned.
start_time | string | Approval initiation time, Unix millisecond timestamp
end_time | string | Approval instance end time: 0 for unfinished approvals, Unix millisecond timestamp
update_time | string | The recent update time of the approval instance, unix millisecond timestamp, used for data version control in pushes. If the `update_mode` value is `UPDATE`, the approval instance information in the Approval Center will be updated only when the passed `update_time` has changed (increased).<br>**Note**: This parameter is primarily used to prevent old data from overwriting new data during concurrency.
display_method | string | How to open an approval instance on the list page<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open with hosting
update_mode | string | Update mode.<br>- When `update_mode` is set to `REPLACE`, the current push data will be taken as the final data each time, and any extra tasks or copy data not included in the current push will be deleted from the Approval Center.<br>- When `update_mode` is set to `UPDATE`, the data in the Approval Center will not be deleted; instead, it will only add new data and update the instance and task data.<br>**Optional values are**:<br>- REPLACE：Full replacement, default<br>- UPDATE：incremental update
task_list | external_instance_task_node\[\] | Task list
task_id | string | Unique identifier within the approval instance to locate data when updating the approval task
user_id | string | The approver user_id. The task will appear in the approver's Pending or Approved list
open_id | string | Approver open_id
title | string | Approval task name
links | external_instance_link | The jump link used in [Pending Approval] or [Approved] is used to jump back to the three-party system pc_link and mobile_link must fill in one, which end of the link is filled in, that is, it will jump to the link, not affected by the platform
pc_link | string | The jump link on the pc side, when the user uses the Feishu pc side, use this field to jump
mobile_link | string | Mobile end jump link, when the user uses Feishu mobile end, use this field to jump
status | string | task status<br>**Optional values are**:<br>- PENDING：Pending approval<br>- APPROVED：Task agreed<br>- REJECTED：Task denied<br>- TRANSFERRED：Task transfer<br>- DONE：The task passed but the approver did not operate it; the approver cannot see the task. If you want to see it, you can copy the person.
extra | string | Extend json, the reason for the end of the task needs to be passed complete_reason field. The enumeration value and the corresponding description:<br>- approved: agreed<br>- rejected: rejected<br>- node_auto_reject: Automatic rejection (due to logical judgment)<br>- specific_rollback: return (including return to the sponsor, return to any intermediate approver)<br>- add: and sign (add a new approver, approve with me)<br>- add_pre: Pre-approver (add new approver, approve before me)<br>- add_post: post-approver (add new approver, approve after me)<br>- delete_assignee: Reductions<br>- forward_resign: transfer (transfer to others for approval)<br>- recall: revocation (withdrawal of documents, invalidation of documents)<br>- delete: delete the approval slip<br>- admin_forward: the administrator operates the forwarding in the background<br>- system_forward: the system automatically transfers<br>- auto_skip: Auto Pass<br>- manual_skip: manually skip<br>- submit_again: resubmit tasks<br>- restart: restart the process<br>- others: others (as a backstop)
create_time | string | Task creation time, Unix millisecond timestamp
end_time | string | Task completion time: 0 for unfinished approvals, Unix millisecond timestamp
update_time | string | The last update time of the task, unix millisecond timestamp, which is used to push data versioning; update the policy update_time in the same instance
action_context | string | Operation context, when the user operates, this parameter is included in the callback request to pass the context data of the task
action_configs | action_config\[\] | Task level operation configuration, fast approval currently supports mobile end operation
action_type | string | Operation type. Each task can be configured with two operations (approve, reject, or any two), and the operations will be displayed in the approval list. When the user operates, the callback request will contain this field, and the three-party approval can receive the operation data of the approver.<br>**Possible values**:<br>- APPROVE：Approve<br>- REJECT：Reject<br>- {KEY}：Any string. If you use any string, you need to provide action_name
action_name | string | The operation name, i18n key is used for foreground presentation, if the action_type is not APPROVAL and REJECT, this field must be provided to display the specific operation name
is_need_reason | boolean | Whether you need an opinion, if true, when the user operates, it will jump to the opinion fill page
is_reason_required | boolean | Approval comment is required
is_need_attachment | boolean | Opinion whether to support uploading attachments
display_method | string | How to open approval tasks on the list page<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open in hosted mode
exclude_statistics | boolean | Tripartite mission support is not included in efficiency statistics.<br>false: Include efficiency statistics.<br>true: efficiency statistics are not included
node_id | string | Node ID: must be satisfied at the same time<br>- In a process, each node id is unique. For example, the Node_id of each node such as "direct manager" and "hierarchical superior" under a process are different<br>- In the same process definition, the same node in different approval instances should Node_id remain unchanged. For example, Zhang San and Li Si initiated leave applications respectively, and the node_id of the "direct manager" node in these two approval instances should remain the same
node_name | string | Node names, such as "Financial Approval" and "Legal Approval", support three languages: Chinese, English and Japanese. Example: i18n@name. The international copy corresponding to the name needs to be uploaded in the i18n_resources
generate_type | string | task generation type<br>**Optional values are**:<br>- EXTERNAL_CONSIGN：Give the agent a completed task<br>- DEFAULT：Default, can be left blank, but do not fill in the blank string.
cc_list | cc_node\[\] | CC list
cc_id | string | Unique identity within the approval instance
user_id | string | CC employee id
open_id | string | CC open id
links | external_instance_link | Jump link, used for the jump pc_link and mobile_link in the [CC My] list, you must fill in one, which end of the link is filled in, that is, you will jump to the link, not affected by the platform
pc_link | string | The jump link on the pc side, when the user uses the Feishu pc side, use this field to jump
mobile_link | string | Mobile end jump link, when the user uses Feishu mobile end, use this field to jump
read_status | string | Read status<br>**Optional values are**:<br>- READ：read<br>- UNREAD：unread
extra | string | Extend json
title | string | CC task name
create_time | string | CC initiation time, Unix millisecond timestamp
update_time | string | CC last update time, unix millisecond timestamp, used to push data versioning update policy same instance update_time
display_method | string | How to open approval tasks on the list page<br>**Optional values are**:<br>- BROWSER：Jump to the default browser of the system to open<br>- SIDEBAR：Feishu middle side drawer open<br>- NORMAL：Feishu inline page opens<br>- TRUSTEESHIP：Open in hosted mode
i18n_resources | i18n_resource\[\] | International copywriting
locale | string | Language options are: zh-CN: Chinese en-US: English ja-JP: Japanese<br>**Optional values are**:<br>- zh-CN：Chinese<br>- en-US：English<br>- ja-JP：Japanese<br>- zh-HK：Traditional Chinese (Hong Kong, China)<br>- zh-TW：Traditional Chinese (Taiwan, China)<br>- de-DE：German<br>- es-ES：Spanish<br>- fr-FR：French<br>- id-ID：Indonesian<br>- it-IT：Italian<br>- ko-KR：Korean<br>- pt-BR：Portuguese<br>- th-TH：Thai<br>- vi-VN：Vietnamese<br>- ms-MY：Malay<br>- ru-RU：Russian
texts | i18n_resource_text\[\] | Copywriting key, value, i18n key starts with @i18n @; this field is mainly used for internationalization, allowing users to transmit copywriting in multiple languages at the same time. The approval center will use the corresponding copywriting according to the user's current voice environment. If the user's current voice environment copywriting, the default language copywriting will be used.
key | string | Copywriting key
value | string | copywriting
is_default | boolean | Whether the default language, the default language needs to include all keys, non-default language If the key does not exist, the default language will be used instead
trusteeship_url_token | string | Document escrow authentication token, the escrow callback will be accompanied by this token to help the business party authenticate
trusteeship_user_id_type | string | The type of user, which affects the selection of the user identity field of the request parameter, including the target user returned by the signature operation. Currently only "user_id" is supported
trusteeship_urls | trusteeship_urls | The URL address of the interface of the document hosting callback access party
form_detail_url | string | Get the url address of the data related to the form schema
action_definition_url | string | Represents the url address for getting approval action area data
approval_node_url | string | Get the url address of the approval record related data
action_callback_url | string | The url address of the callback when the approval operation is performed
pull_business_data_url | string | Obtain the URL address of the hosted dynamic data. When using this interface, you must ensure that the interface address is synchronized in the data of the historical hosted document. If there is no such interface in the historical document, you need to re-synchronize the data of the historical hosted document to update the URL. This interface is used for the interactive use of the Feishu approval front-end and the line of business. Only the specific components of the approval front-end (the components provided by the Feishu approval front-end and the components that need to interface with the line of business) will be required
trusteeship_cache_config | trusteeship_instance_cache_config | Managed pre-cache policy
form_policy | string | Managed pre-cache policy<br>**Optional values are**:<br>- DISABLE：Not enabled, default<br>- IMMUTABLE：Forms do not change with the process<br>- BY_NODE：Update cache following process node changes<br>- BY_USER：Store one copy for each to-do task
form_vary_with_locale | boolean | Whether the form changes with internationalization
form_version | string | The version number of the currently used form, ensure that after the form is changed, the version number is increased, and the actual value is an int64 integer
resource_region | string | The area where the resource is located, the field for internal statistics does not need to be filled in

### Response body example
```json
{
    "code": 0,
    "msg": "Success",
    "data": {
        "data": {
            "approval_code": "81D31358-93AF-92D6-7425-01A5D67C4E71",
            "status": "PENDING",
            "extra": "{\"xxx\":\"xxx\",\"business_key\":\"xxx\"}",
            "instance_id": "24492654",
            "links": {
                "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
            },
            "title": "@i18n@1",
            "form": [
                {
                    "name": "@i18n@2",
                    "value": "@i18n@3"
                }
            ],
            "user_id": "A987sf9s",
            "user_name": "@i18n@9",
            "open_id": "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1",
            "department_id": "OD-8EC33278BC2",
            "department_name": "@i18n@10",
            "start_time": "1556468012678",
            "end_time": "1556468012678",
            "update_time": "1556468012678",
            "display_method": "BROWSER",
            "update_mode": "UPDATE",
            "task_list": [
                {
                    "task_id": "112534",
                    "user_id": "A987sf9s",
                    "open_id": "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1",
                    "title": "i18n1",
                    "links": {
                        "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                        "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
                    },
                    "status": "PENDING",
                    "extra": "{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}",
                    "create_time": "1556468012678",
                    "end_time": "1556468012678",
                    "update_time": "1556468012678",
                    "action_context": "123456",
                    "action_configs": [
                        {
                            "action_type": "APPROVE",
                            "action_name": "@i18n@5",
                            "is_need_reason": false,
                            "is_reason_required": false,
                            "is_need_attachment": false
                        }
                    ],
                    "display_method": "BROWSER",
                    "exclude_statistics": false,
                    "node_id": "Node",
                    "node_name": "i18n@name",
                    "generate_type": "EXTERNAL_CONSIGN"
                }
            ],
            "cc_list": [
                {
                    "cc_id": "123456",
                    "user_id": "12345",
                    "open_id": "ou_ be73cbc0ee35eb6ca54e9e7cc14998c1",
                    "links": {
                        "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                        "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
                    },
                    "read_status": "READ",
                    "extra": "{\"xxx\":\"xxx\"}",
                    "title": "XXX",
                    "create_time": "1556468012678",
                    "update_time": "1556468012678",
                    "display_method": "BROWSER"
                }
            ],
            "i18n_resources": [
                {
                    "locale": "zh-CN",
                    "texts": [
                        {
                            "key": "@i18n@1",
                            "value": "People"
                        }
                    ],
                    "is_default": true
                }
            ],
            "trusteeship_url_token": "788981c886b1c28ac29d1e68efd60683d6d90dfce80938ee9453e2a5f3e9e306",
            "trusteeship_user_id_type": "user_id",
            "trusteeship_urls": {
                "form_detail_url": "https://#{your_domain}/api/form_detail",
                "action_definition_url": "https://#{your_domain}/api/action_definition",
                "approval_node_url": "https://#{your_domain}/api/approval_node",
                "action_callback_url": "https://#{your_domain}/api/action_callback",
                "pull_business_data_url": "https://#{your_domain}/api/pull_business_data"
            },
            "trusteeship_cache_config": {
                "form_policy": "DISABLE",
                "form_vary_with_locale": false,
                "form_version": "1"
            },
            "resource_region": "cn"
        }
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 1390001 | Param is invalid | Parameter error. Troubleshooting steps:<br>- Check the parameters passed during the request according to the parameter descriptions in the API documentation.<br>- If form parameters are passed, verify whether the form control data within the parameters is correct. If the error message includes a control ID (e.g., `Control= widget17261088448220001`), you can call the [View specific approval definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) or [Get single approval instance details](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/get) API to retrieve the response parameter form value, search for the problematic control ID, and check whether the configuration of the control is correct.
400 | 1395001 | There have been some errors. Please try again later | Service error encountered. Troubleshooting steps:<br>1. Refer to the parameter descriptions in the API documentation and check whether the parameters passed in the request are correct. If form parameters are passed (form), ensure the form control data is correct.<br>2. Lower the request frequency, do not synchronize the same approval instance within a short period, please try again later. If the error persists after retrying, please contact [Technical Support](https://applink.feishu.cn/TLJpeNdW).
400 | 1390014 | tenant_id not found | No designated members found.

For more error code information, see [General error codes](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN).

