# Create a task

This interface can create a task and support filling in the basic information of the task, including the title, description and collaborators of the task. On this basis, you can set deadlines and repeat rules when creating tasks, and set tasks as recurring tasks that are executed on a regular basis. By adding collaborators, other users can collaborate on the task. In addition, the interface also provides some fields that support custom content, and the caller can implement custom effects, such as jumping to the specified web page after completing the task.

## Request

Facts |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/task/v1/tasks
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.** | View, create, update, and delete Task (legacy version)(task:task)
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>or<br>`user_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer u-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
---|---|---|---
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)

### Request body

Parameter | Type | Required | Description
---|---|---|---
summary | string | No | The title of the task, as a text string. Use the rich_summary field if you want to insert a URL or @ user in the task summary. When creating a task, the task summary (summary field) and task rich text summary (rich_summary field) cannot be empty at the same time, and at least one of them needs to be filled in.<br>**Notice**：**Example value**: "Complete the writing of OKR for the quarter"<br>**Data validation rules**:<br>- Length range: `0` ～ `1000` characters
description | string | No | The description of the task, as a text string. Use the rich_description field if you want to insert a URL or @ user in the task description.<br><md-alert><br>When both task description and task rich-text description exist, only rich-text description are used.<br>**Example value**: "Review and summarize the content of this meeting, and write and update OKR for this quarter"<br>**Data validation rules**:<br>- Length range: `0` ～ `65536` characters
extra | string | No | Affiliate Information. Users can pass in base64 encoded custom data. If the user needs to remark information about the current task, but it is not displayed externally, this field can be used to store it. This data will be returned to the user when the task details are obtained.<br>**Example value**: "dGVzdA"<br>**Data validation rules**:<br>- Length range: `0` ～ `65536` characters
due | due | No | Due time of the task
time | string | No | Unix timestamp (in seconds) representing the deadline<br>**Example value**: "1623124318"
timezone | string | No | The time zone corresponding to the deadline. The incoming value needs to conform to the IANA Time Zone Database standard, see the specification：[https://www.iana.org/time-zones](https://www.iana.org/time-zones)<br>**Example value**: "Asia/Shanghai"<br>**Default value**: `Asia/Shanghai`
is_all_day | boolean | No | Whether the marked task is an all-day task includes the following values:<br>- true: Indicates that it is an all-day task, and the deadline for the all-day task is 0:00 UTC on the current day.<br>- false: Indicates that it is not an all-day task.<br>**Example value**: false<br>**Default value**: `false`
origin | origin | Yes | Source information of the third-party platform associated with the task
platform_i18n_name | string | Yes | The name of the task source. Used to display on the task center details page. A dictionary is required to support multiple language name mappings. When the application uses a different language, the import source will also display the corresponding content. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**Example value**: "{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}"<br>**Data validation rules**:<br>- Length range: `0` ～ `1024` characters
href | href | No | URL of the details page of the source platform associated with the task
url | string | No | Specific link address. URL only supports parsing http, https. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**Example value**: "https://support.feishu.com/internal/foo-bar"<br>**Data validation rules**:<br>- Length range: `0` ～ `1024` characters
title | string | No | Title that corresponds to the URL<br>**Example value**: "We need assistance to resolve an issue"<br>**Data validation rules**:<br>- Length range: `0` ～ `512` characters
can_edit | boolean | No | This field is used to control whether the task can be edited in Feishu task center, the default is false.<br>**Notice**：**Example value**: true<br>**Default value**: `false`
custom | string | No | Customize complete configuration. This field is used to set a page jump when completing a task, or to display a prompt message. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**Example value**: "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}"<br>**Data validation rules**:<br>- Length range: `0` ～ `65536` characters
collaborator_ids | string\[\] | No | List of collaborator ids added when creating the task. The value passed in is user_id or open_id , determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)<br>**Example value**: ["ou_1400208f15333e20e11339d39067844b"]<br>**Data validation rules**:<br>- Maximum length: `100`
follower_ids | string\[\] | No | A list of follower ids added when creating a task. The value passed in is user_id or open_id , determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)<br>**Example value**: ["ou_1400208f15333e20e11339d39067844b"]<br>**Data validation rules**:<br>- Maximum length: `100`
repeat_rule | string | No | Regular expression for repeating tasks. For the syntax format, see [RRule Syntax Specification](https://www.ietf.org/rfc/rfc2445.txt) section 4.3.10<br>**Example value**: "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
rich_summary | string | No | Rich-text task summary. For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>When creating a task, the task summary (summary field) and task rich text summary (rich_summary field) cannot be empty at the same time, and at least one of them needs to be filled in.<br>**Example value**: "Complete the writing of OKR for the quarter\[Feishu open platform](https://open.feishu.cn/)"<br>**Data validation rules**:<br>- Length range: `0` ～ `1000` characters
rich_description | string | No | Rich-text task description. For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>**Example value**: "Review and summarize the content of this meeting, and write and update OKR for this quarter\[Feishu open platform](https://open.feishu.cn/)"<br>**Data validation rules**:<br>- Length range: `0` ～ `65536` characters

### Request body example
```json
{
    "summary": "Drink eight glasses of water a day and relax your mind and body.",
    "description": "Eat more fruits, exercise more, live a healthy life, and work happily.",
    "rich_summary": "rich_summary[feishu open-platform](https://open.feishu.cn)",
    "rich_description": "rich_description[feishu open-platform](https://open.feishu.cn)",
    "extra": "dGVzdA==",
    "due": {
        "time": "1623124318",
        "timezone": "Asia/Shanghai",
        "is_all_day": false
    },
    "origin": {
        "platform_i18n_name": "{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}",
        "href": {
            "url": "https://support.feishu.com/internal/foo-bar",
            "title": "We need assistance to resolve an issue"
        }
    },
    "can_edit":true,
    "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
    "follower_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "collaborator_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
task | task | Returns a created task.
id | string | Unique ID of the task, for example "83912691-2e43-47fc-94a4-d512e03984fa"
summary | string | The title of the task, as a text string. Use the rich_summary field if you want to insert a URL or @ user in the task summary. When creating a task, the task summary (summary field) and task rich text summary (rich_summary field) cannot be empty at the same time, and at least one of them needs to be filled in.<br><md-alert><br>When both the task summary and the task rich-text summary exist, only the rich text title is used.
description | string | The description of the task, as a text string. Use the rich_description field if you want to insert a URL or @ user in the task description.<br>**Notice**：
complete_time | string | The completion timestamp of the task (in seconds). A completion time of 0 indicates that the task has not been completed.<br>Partial completion is not supported, and this field will have a non-zero value only if the entire task is completed.
creator_id | string | The creator ID of the task.<br>The query field user_id_type is used to control the type of creator_id in the returned body. If not passed, it will return open_id by default.<br>In particular, when using tenant_access_token to call the interface, if the user_id_type is open id, the open id representing the identity of the application is returned. When the user_id_type is user_id, the creator_id is not returned. The reason is that user_id represents the id of a real Feishu user, and the application identity does not have user_id. Calling the interface with user_access_token returns the creator normally.
extra | string | Affiliate Information. Users can pass in base64 encoded custom data. If the user needs to remark information about the current task, but it is not displayed externally, this field can be used to store it. This data will be returned to the user when the task details are obtained.
create_time | string | Unix timestamp (in seconds) of the creation time of the task
update_time | string | Unix timestamp (in seconds) of the task's update time<br>update_time is the same as create_time when creating a task
due | due | Due time of the task
time | string | Unix timestamp (in seconds) representing the deadline
timezone | string | The time zone corresponding to the deadline. The incoming value needs to conform to the IANA Time Zone Database standard, see the specification：[https://www.iana.org/time-zones](https://www.iana.org/time-zones)
is_all_day | boolean | Whether the marked task is an all-day task includes the following values:<br>- true: Indicates that it is an all-day task, and the deadline for the all-day task is 0:00 UTC on the current day.<br>- false: Indicates that it is not an all-day task.
origin | origin | Source information of the third-party platform associated with the task
platform_i18n_name | string | The name of the task source. Used to display on the task center details page. A dictionary is required to support multiple language name mappings. When the application uses a different language, the import source will also display the corresponding content. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
href | href | URL of the details page of the source platform associated with the task
url | string | Specific link address. URL only supports parsing http, https. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
title | string | Title that corresponds to the URL
custom | string | Customize complete configuration. This field is used to set a page jump when completing a task, or to display a prompt message. For details, see: [Supplementary directions of task fields](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
source | int | Source from which the task is created<br>**Optional values are**:<br>- 0：Unknown type<br>- 1：The task is created by the source task center.<br>- 2：The task converted from a source message<br>- 3：Source Docs<br>- 4：Product of the source document<br>- 5：Source PANO<br>- 6：The task created based on the tenant_access_token of the source<br>- 7：The task created based on the user_access_token of the source<br>- 8：Source Docs in the new version
followers | follower\[\] | Followers of the task
id | string | ID of the task follower (to be deprecated, use id_list)
id_list | string\[\] | Multiple follower ids to be deleted.
collaborators | collaborator\[\] | Collaborators of the task
id | string | The ID of the task collaborator. The value passed in is user_id or open_id, determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)<br><md-alert><br>Deprecated, reserved for forward compatibility in the early days when only one person was added at a time, but it is no longer recommended, it is recommended to use the id_list field
id_list | string\[\] | List of collaborator ids added when creating the task. The value passed in is user_id or open_id, determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)
collaborator_ids | string\[\] | List of collaborator ids added when creating the task. The value passed in is user_id or open_id , determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)
follower_ids | string\[\] | A list of follower ids added when creating a task. The value passed in is user_id or open_id , determined by user_id_type. For details, see: [How to get ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)
repeat_rule | string | Regular expression for repeating tasks. For the syntax format, see [RRule Syntax Specification](https://www.ietf.org/rfc/rfc2445.txt) section 4.3.10
rich_summary | string | Rich-text task summary. For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>When creating a task, the task summary (summary field) and task rich text summary (rich_summary field) cannot be empty at the same time, and at least one of them needs to be filled in.
rich_description | string | Rich-text task description. For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)

### Response body example
```json
{
    "code": 0,
    "data": {
        "task": {
            "can_edit": true,
            "complete_time": "0",
            "create_time": "1630304148",
            "creator_id": "ou_05b67908bc5d12a086e909a076f7f1b6",
            "summary": "Drink eight glasses of water a day and relax your mind and body.",
            "rich_summary":"rich_summary feishu open-platform\n",
            "description": "Eat more fruits, exercise more, live a healthy life, and work happily.",
            "rich_description": "rich_desciption feishu open-platform\n",
            "due": {
                "time": "1623124318",
                "timezone": "Asia/Shanghai"
            },
            "extra": "dGVzdA==",
            "id": "68c9b9ff-d5b5-41bf-b407-6d956f23143f",
            "origin": {
                "href": {
                    "title": "We need assistance to resolve an issue",
                    "url": "https://support.feishu.com/internal/foo-bar"
                },
                "platform_i18n_name": "{\"en_us\":\"IT Workspace\",\"zh_cn\":\"IT 工作台\"}"
            },
            "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
            "update_time": "1630304149",
            "source": 6,
            "collaborators": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "followers": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
        },
    },
    "msg": "success"
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 1470400 | The request failed due to incorrect request parameters. | Generally, there may be a problem with the request parameters, causing the request to fail. It is recommended to check according to the specific error returned.
401 | 1470403 | The identity token is incorrect. It should be either user_access_token or tenant_access_token. | The identity token is incorrect. It should be either user_access_token or tenant_access_token.
400 | 1470410 | Failed to parse rich_summary. | Rich text summary parsing error, it is recommended to check whether the rich_summary has format error, For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)
400 | 1470411 | Failed to parse rich_description. | Rich text description parsing error, it is recommended to check whether the rich_description has format error, For syntax format see: [Markdown module](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)
400 | 1470414 | Invalid timezone. | The time zone information is not compliant. It is recommended to check whether the timezone field is in the correct format. The incoming value needs to conform to the IANA Time Zone Database standard, see the specification：[Time Zone Database](https://www.iana.org/time-zones)
400 | 1470415 | Invalid platform_i18n_name. | The task source information is not compliant. It is recommended to check whether the platform_i18n_name field is in the correct format, an unsupported locale name may have been passed in.
400 | 1470416 | Both summary and rich_summary are empty. | Neither the title nor the rich text title has set content. When creating a task, one of the fields must be filled in
400 | 1470434 | Invalid repeat rule, please check the format. | The duplicate rule cannot be parsed, it may be an incorrect format passed in, please check whether it conforms to the grammar specification.
400 | 1470435 | Failed to decode extra by base64. | The extra field cannot be parsed in base64 format, please check whether the incoming content is base64 encoded and passed in.
400 | 1470436 | Failed to parse url of origin, should start with http, https or applink. | Failed to parse URL in Origin, please check if it starts with http, https or applink.
400 | 1470437 | Summary or description length exceed limit, the maximum length of summary is 256, the maximum length of description is 65536. | Summary or description length exceed limit, the maximum length of summary is 256, the maximum length of description is 65536.
400 | 1470438 | Invalid custom, please check the format. | The format of the Custom field is incorrect, please check according to the field description.
400 | 1470439 | Failed to get time by timestamp. | The timestamp could not be parsed, please check whether the timestamp conforms to the specification according to the field description.
429 | 1470450 | There are too many requests currently, please try again later. | There are too many requests currently initiated at the same time, and the peak value is high, resulting in current limit, please try again later.
500 | 1470600 | Failed to create task. | The task creation failed. If retrying cannot solve the problem, please contact Feishu technicians to assist in troubleshooting.
400 | 1470740 | Text content fails to pass the audit. | Generally, the title or description of the task or the rich text content contains illegal content and does not pass the safe content check.