# View third-party approval definition

Call this interface to obtain detailed information of the approval definition using the third-party approval definition code. This includes the name of the third-party approval definition, description, third-party approval initiation link, callback URL, and the list of visible personnel for the approval definition.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/approval/v4/external_approvals/:approval_code
HTTP Method | GET
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 definition(approval:external_approval)
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>Obtain user ID(contact:user.employee_id: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>[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)

### Path parameters

Parameter | Type | Description
---|---|---
approval_code | string | Third-party approval definition code can be obtained by:<br>- Calling [Create Third-Party Approval Definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/external_approval/create), which will return the approval definition code.<br>- Logging into the approval management backend and obtaining it from the URL of the specified approval definition. For detailed instructions, see [What is Approval Code](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/overview-of-approval-resources#8151e0ae).<br>**Example value**: "7C468A54-8745-2245-9675-08B7C63E7A85"

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
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>**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)

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
approval_name | string | Approval definition name. The current parameter returns a key that starts with @i18n@. You need to look up the corresponding value of the current key through the i18n_resources.texts parameter value.
approval_code | string | The approval_code passed when creating a third-party approval definition.<br>**Note**: The approval_code request parameter of the [Create Third-Party Approval Definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/external_approval/create) interface may not be the same as the approval_code response parameter. The current parameter returns the value of the approval_code used as the request parameter.
group_code | string | The approval group to which the approval definition belongs, which is user-defined.
group_name | string | Group name. The current parameter returns a key that starts with @i18n@. You need to look up the corresponding value of the current key through the i18n_resources.texts parameter value.
description | string | Description of the approval definition. The current parameter returns a key that starts with @i18n@. You need to look up the corresponding value of the current key through the i18n_resources.texts parameter value.
external | approval_create_external | Third-party approval related
biz_name | string | In the list, the prompt indicating where the approval comes from. The current parameter returns a key that starts with @i18n@. You need to look up the corresponding value of the current key through the i18n_resources.texts parameter value.
biz_type | string | This field is used to identify which business party the approval definition belongs to. It is user-defined , and the same value can be used for multiple approval definitions.The field is to attribute multiple approval definitions to the same business party. Therefore, when searching for approvals, if the business party has configured an external approval search with the same biz_type parameter, the parameters with biz_type will be filtered out from the search provided by the Approval Center, and the search will be performed from the configured URL.
create_link_mobile | string | Initiation link in the mobile app. If the link is set, the approval will be displayed in the approval initiation page on the mobile, and users will be redirected to the link to initiate an approval after clicking.<br>If this field is left empty, the approval will not be displayed in themobile app.
create_link_pc | string | Initiation link on PC. If the link is set, the approval will be displayed in the approval initiation page on PC, and users will be redirected to the link to initiate an approval after clicking.<br>If this field is left empty, the approval will not be displayed on PC.
support_pc | boolean | Whether the approval instance, approval tasks, and approval CC are displayed on PC. If the value is true, the instance information under this definition will be displayed on PC; otherwise, it will not be displayed.
support_mobile | boolean | Whether the approval instance, approval tasks, and approval CC are displayed on the mobile. If the value is true, the instance information under this definition will be displayed on the mobile; otherwise, it will not be displayed.
support_batch_read | boolean | Whether marking as read in batches is supported
enable_mark_readed | boolean | Whether marking as read is supported（This field is invalid）
enable_quick_operate | boolean | Whether quick action is supported
action_callback_url | string | Third-party's action callback URL. This URL is called by the Approval Center to notify the third-party system when the task approver of the [Pending] list clicks "Approve" or "Reject".Refer to [Quick Approval Callback](https://open.feishu.cn/document/ukTMukTMukTM/ukjNyYjL5YjM24SO2IjN/quick-approval-callback)
action_callback_token | string | The token brought during the callback, used by the business system to verify that the request comes from the approval center.
action_callback_key | string | Request parameter encryption key. If this parameter is configured, the request parameters will be encrypted, and the request needs to be decrypted upon reception. For encryption and decryption algorithms, refer to [External Option Description](https://open.feishu.cn/document/ukTMukTMukTM/uADM4QjLwADO04CMwgDN).
allow_batch_operate | boolean | Whether batch action is supported
exclude_efficiency_statistics | boolean | Whether approval process data is not included in efficiency statistics
viewers | approval_create_viewers\[\] | List of users who can view. Multiple viewers can be configured at the same time, and only users within the visible scope can see the approval in the approval initiation page.
viewer_type | string | Viewer type<br>**Optional values are**:<br>- TENANT：Users in a tenant<br>- DEPARTMENT：Specified departments<br>- USER：Specified users<br>- NONE：No one
viewer_user_id | string | When viewer_type is USER,  return the user id according to user_id_type
viewer_department_id | string | When the viewer_type is set to DEPARTMENT, this parameter has a return value, which is the ID of the specified department.
i18n_resources | i18n_resource\[\] | Internationalized text
locale | string | Language<br>**Optional values are**:<br>- zh-CN：Chinese<br>- en-US：English<br>- ja-JP：Japanese
texts | i18n_resource_text\[\] | Copywriting Key: Value. The Key starts with @i18n@ and matches other parameter Keys.<br>**Note**: This field is mainly used for internationalization adaptation, allowing the setting of copywriting in multiple languages simultaneously. The approval center will use the matching copywriting based on the actual user's current language environment. If the user's current language environment copywriting is not set, the default language copywriting will be used.
key | string | Copywriting key
value | string | Copywriting
is_default | boolean | Whether to use the default language.
managers | string\[\] | Fill in the process managers id according to the user_id_type

### Response body example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_name": "@i18n@1",
        "approval_code": "permission_test",
        "group_code": "work_group",
        "group_name": "@i18n@2",
        "description": "@i18n@2",
        "external": {
            "biz_name": "@i18n@3",
            "biz_type": "permission",
            "create_link_mobile": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/approval-form/index?id=9999",
            "create_link_pc": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/create-form/index?id=9999",
            "support_pc": true,
            "support_mobile": true,
            "support_batch_read": true,
            "enable_mark_readed": true,
            "enable_quick_operate": true,
            "action_callback_url": "http://www.feishu.cn/approval/openapi/instanceOperate",
            "action_callback_token": "sdjkljkx9lsadf110",
            "action_callback_key": "gfdqedvsadfgfsd",
            "allow_batch_operate": true,
            "exclude_efficiency_statistics": true
        },
        "viewers": [
            {
                "viewer_type": "USER",
                "viewer_user_id": "19a294c2",
                "viewer_department_id": "od-ac9d697abfa990b715dcc33d58a62a9d"
            }
        ],
        "i18n_resources": [
            {
                "locale": "zh-CN",
                "texts": [
                    {
                        "key": "@i18n@1",
                        "value": "People"
                    }
                ],
                "is_default": true
            }
        ],
        "managers": [
            "19a294c2"
        ]
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 1390001 | invalid params | 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 | 1390002 | approval code not found | Cannot find approval definition code. Check whether the passed approval definition code is correct.<br>Methods to obtain the approval definition code:<br>- After calling the [Create approval definition](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/create) API, get it from the response parameter approval_code.<br>- Log into the approval management backend and obtain it from the URL of the specified approval definition. For detailed operations, refer to [What is approval code](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/overview-of-approval-resources#8151e0ae).
400 | 1390016 | approval is deleted | Approval definition has been deleted, the current operation is not supported.

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