# Sync of third-party approval instances
**Notice**：This API has been upgraded to enhance its security. We recommend that you migrate to the [new version>>](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/external_instance/create)
<br>
Approval transfer lies in the third-party system instead of the Approval Center. The approval instances, approval tasks, and approval CC data generated after approval transfer are synced from the third-party system to the Approval Center.<br>
<br>
Users can browse the instances, tasks, and CC information synced from the third-party system in the Approval Center, and can redirect to the third-party system for more detailed viewing and action. The instance information is in the [Initiated] list, the task information is in the [Pending] and [Approved] lists, and the CC information is in the [CC'd] list.

<br>
The third-party system can also configure the callback API for approval tasks, so that the approver can directly perform the approval action in the Approval Center, and the Approval Center will call back the third-party system. After receiving the callback, the third-party system will update the task information and sync the new task information back to the Approval Center to form a closed loop.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://www.feishu.cn/approval/openapi/v2/external/instance/create
HTTP Method | POST
Supported app types | Custom App、Store App
Required scopes<br>**The scopes required to call this API. You can call the API with any of the scopes.** | Access Approval(approval:approval:readonly)

### 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>[Learn more about how to access and use access_token](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"

### Request body

Parameter | Type | Description
---|---|---
content<br>`Required` | string | JSON string

**Third-party approval JSON**

Parameter | Type | Description | Example
---|---|---|---
approval_code<br>`Required` | string | Approval definition code, which creates the value returned by the approval definition to indicate which process the instance belongs to. This field affects the title of the instance in the list, which is taken from the name field of the corresponding definition. | 81D31358-93AF-92D6-7425-01A5D67C4E71
instance_id<br>`Required` | string | The unique ID of approval instance defined by users. It is required to be unique under tenant and app. | 24492654
status<br>`Required` | string | Approval instance status  <br>**Optional values are:**  <br>- `PENDING`: Under review<br>- `APPROVED`: The request is approved when the approval process ends.<br>- `REJECTED`: The request is rejected when the approval process ends.<br>- `CANCELED`: The approval is canceled by the initiator.<br>- `DELETED`: The approval is deleted.<br>- `HIDDEN`: Status is hidden (i.e. not displayed). | PENDING
extra | string | Approval instance extension JSON | {"xxx":"xxx"}
links<br>`Required` | map | Approval instance link collection, which is used to redirect to the third-party system from the [Initiated] list.<br>Either the pc_link field or mobile_link field must be filled in to specify the link for redirection, which is not affected by the platform. | &nbsp;
&emsp;∟&nbsp;pc_link<br>`Required` | string | Redirection link for PC, which is used for redirection when users use Feishu on PC | https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9cfc38e07a9101&path=pc/pages/detail?id=1234
&emsp;∟&nbsp;mobile_link`required` | string | Redirection link for mobile, which is used for redirection when users use Feishu on mobile | https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
title | string | Approval display name. If this field is filled in, the approval title in the approval list will use this field. If this field isn't filled in, the approval title will use the name of the approval definition. | @i18n@1
form | list | Form data filled in when a user submits application, which is displayed in all the approval lists. More than one value can be passed. However, in the Approval Center, the first 2 values are displayed on PC, while the first 3 values on mobile. The display length can't exceed 2,048 characters. | [<br>{<br>"name": "@i18n@2",<br>"value": "@i18n@3"<br>}<br>]
&emsp;∟&nbsp;name | string | Form field name | @i18n@2
&emsp;∟&nbsp;value | string | Form value | @i18n@3
user_id`` | string | Approver initiator's user_id. The initiator can view all initiated approvals in the [Initiated] list.<br>In the [Pending], [Approved], and [CC'd] lists, this field shows the initiator of the approval. Either the initiator's open ID or user ID is required. | a987sf9s
user_name | string | Approval initiator's user name. If the initiator isn't a real user (for example, a department) and has no user ID, use this field to pass the name. | @i18n@9
open_id | string | Either the initiator's open ID or user ID is required. | ou_be73cbc0ee35eb6ca54e9e7cc14998c1
department_id | string | Initiator department, used in the list to display the department which the initiator belongs to.<br>This field isn't displayed if it isn't passed.<br>If the user hasn't joined any department, the tenant name is displayed when "" is passed.<br>If the department_name field is passed, the department name is displayed. | od-8ec33278bc2
department_name | string | Approval initiator's department. If the initiator isn't a real user (for example, a department) and has no department_id, use this field to pass the name. | @i18n@10
start_time<br>`Required` | long | Approval initiation time (Unix timestamp in ms) | 1556468012678
end_time<br>`Required` | long | Approval instance end time: The value is 0 for uncompleted approvals (Unix timestamp in ms) | 1556468012678
update_time<br>`Required` | long | Last update time of the approval instance, used to push data version control.<br>If the update_mode value is UPDATE, the approval instance information in the Approval Center will only be updated when the passed update_time changes (becomes larger).<br>This field is mainly used to avoid updating new data with old data when concurrency occurs. | 1556468012678
display_method | string | The way to open the approval instance on the list page.<br>**Optional values are:**<br>- `BROWSER`: Opens by redirecting to the default system browser<br>- `SIDEBAR`: Opens in the sidebar of Feishu<br>- `NORMAL`: Opens in the page embedded in Feishu | BROWSER
update_mode | string | Update method  <br>**Optional values are:**<br>- `REPLACE`: Replaces all. The value is set by default.<br>- `UPDATE`: Updates incrementally.<br>When update_mode=REPLACE, each time the currently pushed data is taken as the final data, and the redundant tasks and CC data in the Approval Center will be deleted (not in the data pushed this time).<br>When update_mode=UPDATE, the data in the Approval Center won't be deleted, but only the instance and task data will be added and updated. | UPDATE
task_list<br>`Required` | list | Task list | Notes: The maximum number of tasks is 200.
&emsp;∟&nbsp;task_id<br>`Required` | string | The unique ID within the approval instance, which is used to locate data when updating approval tasks | 112534
&emsp;∟&nbsp;user_id<br>`Required` | string | Approver's user_id. The task will appear in the [Pending] or [Approved] list of the approver. | a987sf9s
&emsp;∟&nbsp;open_id | string | Either the approver's open ID or user ID is required. | ou_be73cbc0ee35eb6ca54e9e7cc14998c1
&emsp;∟&nbsp;title | string | Approval task name | i18n1
&emsp;∟&nbsp;links`required` | map | Redirection link in the [Pending] or [Approved], used to redirect to the third-party system<br>Either the pc_link field or mobile_link field must be filled in to specify the link for redirection, which is not affected by the platform. | &nbsp;
&emsp;&emsp;∟&nbsp;pc_link`required` | string | Redirection link for PC, which is used for redirection when users use Feishu on PC | https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9cfc38e07a9101&path=pc/pages/detail?id=1234
&emsp;&emsp;∟&nbsp;mobile_link`required` | string | Redirection link for mobile, which is used for redirection when users use Feishu on mobile | https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
&emsp;∟&nbsp;status<br>`Required` | string | Task status  <br>**Optional values are:**<br>- `PENDING`: Under review<br>- `APPROVED`: The task is approved<br>- `REJECTED`: The task is rejected<br>- `TRANSFERRED`: The task is transferred<br>- `DONE`: The task is approved but hasn't been processed by the approver. The approver can't see the task. You can CC this individual to make the task visible. | &nbsp;
&emsp;∟&nbsp;extra | string | Extend json, the reason for the end of the task needs to be passed complete_reason field. Enumeration values and corresponding descriptions: <br>- approved: agreed <br>- rejected: rejected <br>- node_auto_reject: Automatic rejection (due to logical judgment) <br>- specific_rollback: return (including return to the originator, 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 someone else for approval) <br>- recall: revocation (withdrawal of documents, invalidation of documents) <br>- delete: delete the approval slip <br>- admin_forward: Administrator in the background operation transfer <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 the bottom line) | {\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}
&emsp;∟&nbsp;create_time<br>`Required` | long | Task creation time (Unix timestamp in ms) | 1556468012678
&emsp;∟&nbsp;end_time<br>`Required` | long | Task completion time: The value is 0 for uncompleted approvals (Unix timestamp in ms) | 1556468012678
&emsp;∟&nbsp;update_time `required` | long | Last update time of the task, used to push data version control.<br>The update policy is the same as the update_time in instance. | 1556468012678
&emsp;∟&nbsp;action_context | string | Action context, which is taken in the callback request to pass the context data of the task as users perform actions | 123456
&emsp;∟&nbsp;action_configs | list | Task-level action configuration. Quick approval is available on mobile. | &nbsp;
&emsp;&emsp;∟&nbsp; action_type <br>`Required` | string | Action type. Each task can be configured with 2 actions, which will be displayed in the approval list. When users perform actions, the callback request will carry this field, indicating whether the user has approved or rejected the action.<br>**APPROVE** - Approved<br>**REJECT** - Rejected<br>**{KEY}** - Arbitrary string. The action name is required when arbitrary string is used. | APPROVE
&emsp;&emsp;∟&nbsp; action_name | string | Action name. The i18n key is used for frontend display. If the action_type field value is neither APPROVAL nor REJECT, this field is required to display a specific action name. | @i18n@5
&emsp;&emsp;∟&nbsp; is_need_reason | bool | Whether the comments are required. If true, users will be redirected to the page to fill in comments when they perform actions. | false
&emsp;&emsp;∟&nbsp; is_reason_required | bool | Whether the approval comments are required. | false
&emsp;&emsp;∟&nbsp; is_need_attachment | bool | Whether attachments can be uploaded for the comments | false
&emsp;∟&nbsp;display_method | string | The way to open the approval task on the list page.<br>**Optional values are:**<br>- `BROWSER`: Opens by redirecting to the default system browser<br>- `SIDEBAR`: Opens in the sidebar of Feishu<br>- `NORMAL`: Opens in the page embedded in Feishu | BROWSER
&emsp;∟&nbsp; exclude_statistics | bool | Tripartite mission support is not included in efficiency statistics.<br>false: Include efficiency statistics.<br>true: not included in efficiency statistics | false
&emsp;∟&nbsp; node_id | string | Node id: must meet both <br>- In a process, each node id is unique. For example, the Node_id of each node such as "direct manager" and "next-level superior" in 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
&emsp;∟&nbsp; node_name | string | Node names, such as "Financial Approval" and "Legal Approval", support three languages: Chinese, English and Japanese. Example: i18n@name. You need to pass the internationalized copy corresponding to the name in the i18n_resources | i18n@name
cc_list | list | CC list | Notes: The maximum number of CCs is 200.
&emsp;∟&nbsp;cc_id<br>`Required` | string | Unique ID in the approval instance | 12345
&emsp;∟&nbsp;user_id<br>`Required` | string | CC employee ID | 12345
&emsp;∟&nbsp;open_id | string | Either the CC sender's open ID or user ID is required. | ou_be73cbc0ee35eb6ca54e9e7cc14998c1
&emsp;∟&nbsp;links<br>`Required` | map | Redirection link, used for redirection in the [CC'd] list<br>Either the pc_link field or mobile_link field must be filled in to specify the link for redirection, which is not affected by the platform. | &nbsp;
&emsp;&emsp;∟&nbsp;&nbsp;pc_link | string | Redirection link for PC, which is used for redirection when users use Feishu on PC | https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9cfc38e07a9101&path=pc/pages/detail?id=1234
&emsp;&emsp;∟&nbsp;&nbsp;mobile_link | string | Redirection link for mobile, which is used for redirection when users use Feishu on mobile | https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
&emsp;∟&nbsp;read_status<br>`Required` | string | Read status. An empty cell indicates that the read/unread status is unavailable:  <br>**Optional values are:**<br>- `READ`: Read<br>- `UNREAD`: Unread | READ
&emsp;∟&nbsp;extra | string | Extension JSON | {<br>"xxx":"xxx"<br>}
&emsp;∟&nbsp;title | string | CC task name | xxx
&emsp;∟&nbsp;create_time`required` | long | CC initiation time (Unix timestamp in ms) | 1556468012678
&emsp;∟&nbsp;update_time`required` | long | Last update time of CC, used to push data version control.<br>The update policy is the same as the update_time in instance. | 1556468012678
&emsp;∟&nbsp;display_method | string | The way to open the approval task on the list page.<br>**Optional values are:**<br>- `BROWSER`: Opens by redirecting to the default system browser<br>- `SIDEBAR`: Opens in the sidebar of Feishu<br>- `NORMAL`: Opens in the page embedded in Feishu | BROWSER
i18n_resources`required` | list | Internationalized text | &nbsp;
&emsp;∟&nbsp;locale`required` | string | Language<br>- `zh-CN`: Chinese<br>- `en-US`: English<br>- `ja-JP`: Japanese | zh-CN
&emsp;∟&nbsp;is_default`required` | bool | Whether the default language | true
&emsp;∟&nbsp;texts`required` | map | Key, value, and i18n key of copy starts with  @i18n@.<br>This field is mainly used for internationalized text. Word order users can pass texts in multiple languages at the same time, and the Approval Center will use the corresponding text according to the user's language environment. If the text of the user's language environment isn't passed, the text of default language will be used. | {<br>"@i18n@1": "Permission request",<br>"@i18n@2": "OA approval",<br>"@i18n@3": "Permission"<br>}

Notes:
- It is required to ensure the uniqueness of various unique IDs in the approval instance, even if they don't belong to the same entity.

```json
{
    "content": "{\"approval_code\":\"60D0F7A2-052D-49E9-B570-C29C836CDF8E\",\"instance_id\":\"216263\",\"status\":\"PENDING\",\"extra\":\"\",\"links\":{\"pc_link\":\"http://182.50.118.46:38080/spa/workflow/static4form/index.html?#/main/workflow/req?requestid=\",\"mobile_link\":\"http://182.50.118.46:38080/spa/workflow/static4form/index.html?#/main/workflow/req?requestid=\"},\"title\":\"@i18n@1\",\"form\":[{\"name\":\"@i18n@2\",\"value\":\"@i18n@3\"}],\"user_id\":\"52d6585f\",\"user_name\":\"342a\",\"open_id\":\"123\",\"department_id\":\"od-8ec33ffec336c3a39a278bc25e931676\",\"department_name\":\"XXXX\",\"start_time\":1622444502000,\"update_time\":1622444502000,\"end_time\":0,\"update_mode\":\"REPLACED\",\"task_list\":[{\"task_id\":\"112253\",\"user_id\":\"52d6585f\",\"links\":{\"pc_link\":\"http://\",\"mobile_link\":\"http://\"},\"status\":\"PENDING\",\"extra\":\"\",\"title\":\"Approve\",\"create_time\":1566468012678,\"end_time\":0,\"update_time\":1566468012678,\"action_context\":\"123456\",\"action_configs\":[{\"action_type\":\"APPROVE\",\"action_name\":\"@i18n@9\",\"is_need_reason\":true,\"is_reason_required\":true,\"is_need_attachment\":true}]}],\"cc_list\":[{\"cc_id\":\"1231243\",\"user_id\":\"a987sf9s\",\"open_id\":\"\",\"links\":{\"pc_link\":\"http://\",\"mobile_link\":\"http://\"},\"read_status\":\"READ\",\"extra\":\"\",\"title\":\"XXX\",\"create_time\":1556468012678,\"update_time\":1566468012678}],\"i18n_resources\":[{\"locale\":\"zh-CN\",\"is_default\":true,\"texts\":{\"@i18n@1\":\"Leave\",\"@i18n@2\":\"Day\",\"@i18n@3\":\"2020-08-01\"}},{\"locale\":\"en-US\",\"is_default\":false,\"texts\":{\"@i18n@1\":\"Leave\",\"@i18n@2\":\"Day\",\"@i18n@3\":\"2020-08-01\"}},{\"locale\":\"ja-JP\",\"is_default\":false,\"texts\":{\"@i18n@1\":\"Leave\",\"@i18n@2\":\"Day\",\"@i18n@3\":\"2020-08-01\"}}]}"
}
```

## Response

### Response body

|Parameter|Type|Required|Description|
|-|-|-|-|
|code|int|Return code. A value other than 0 indicates failure.|
|msg|string|Yes|Return code description|
|data | map |Yes| Returned business information |

### Response body example

```json
{
    "code": 0,
    "msg": "success",
    "data": {
    }
}
```

