Adds a new item to an existing list.
POSThttps://slack-gov.com/api/slackLists.items.createapplication/x-www-form-urlencodedapplication/jsontokenAuthentication token bearing required scopes. Tokens should be passed as an HTTP Authorization header or alternatively, as a POST parameter.
xxxx-xxxxxxxxx-xxxxThis method is used to create a new item (record) in an existing list.
The item will be created with the field values specified in the initial_fields parameter. Each field corresponds to a column in the list and must reference a valid column_id.
Provide field values using the initial_fields parameter:
{
"list_id": "F1234ABCD",
"initial_fields": [
{
"column_id": "Col10000000",
"rich_text": [
{
"type": "rich_text",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Complete project documentation"
}
]
}
]
}
]
}
]
}
Create a copy of an existing item by specifying duplicated_item_id:
{
"list_id": "F1234ABCD",
"duplicated_item_id": "Rec12345678"
}
Create a subtask by specifying parent_item_id:
{
"list_id": "F1234ABCD",
"parent_item_id": "Rec12345678",
"initial_fields": [
{
"column_id": "Col10000000",
"select": ["OptHIGH123"]
}
]
}
The initial_fields parameter supports all column types available in Lists. Here are the supported field formats:
{
"column_id": "Col123",
"rich_text": [
{
"type": "rich_text",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Your text content"
}
]
}
]
}
]
}
{
"column_id": "Col123",
"user": ["U1234567", "U2345678"]
}
{
"column_id": "Col123",
"date": ["2024-12-31"]
}
{
"column_id": "Col123",
"select": ["OptionId123"]
}
{
"column_id": "Col123",
"checkbox": true
}
{
"column_id": "Col123",
"number": [5000]
}
{
"column_id": "Col123",
"email": ["contact@example.com"]
}
{
"column_id": "Col123",
"phone": ["+1-555-123-4567"]
}
{
"column_id": "Col123",
"attachment": ["F1234567890"]
}
{
"column_id": "Col123",
"link": [
{
"original_url": "https://example.com",
"display_as_url": false,
"display_name": "Example Website"
}
]
}
{
"column_id": "Col123",
"message": ["https://yourteam.slack.com/archives/C1234567890/p1234567890123456"]
}
{
"column_id": "Col123",
"rating": [4]
}
{
"column_id": "Col123",
"timestamp": [1704067200]
}
{
"column_id": "Col123",
"channel": ["C1234567890"]
}
{
"column_id": "Col123",
"reference": [
{
"file": {
"file_id": "F1234567890"
}
}
]
}
Format
The response includes the created item with all its field values, plus metadata:
id: The unique identifier for the created itemlist_id: The list the item belongs todate_created: Unix timestamp when the item was createdcreated_by: User ID who created the itemupdated_by: User ID who last updated the itemupdated_timestamp: String timestamp of last updateparent_record_id: Present if this is a subtaskfields: Array of all field values with their formatted representationsCreate a simple task item with text and date fields
{
"ok": true,
"item": {
"id": "Rec12345678",
"list_id": "F1234ABCD",
"date_created": 1704067200,
"created_by": "U1234567",
"updated_by": "U1234567",
"updated_timestamp": "1704067200",
"fields": [
{
"key": "title",
"column_id": "Col10000000",
"value": "[{\"type\":\"rich_text\",\"block_id\":\"abc123\",\"elements\":[{\"type\":\"rich_text_section\",\"elements\":[{\"type\":\"text\",\"text\":\"Complete project documentation\"}]}]}]",
"text": "Complete project documentation",
"rich_text": [
{
"type": "rich_text",
"block_id": "abc123",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Complete project documentation"
}
]
}
]
}
]
},
{
"key": "due_date",
"column_id": "Col10000001",
"value": "2024-03-20",
"date": [
"2024-03-20"
]
}
]
}
}Create a subtask by specifying a parent_item_id
{
"ok": true,
"item": {
"id": "Rec11111111",
"list_id": "F1234ABCD",
"date_created": 1704067200,
"created_by": "U1234567",
"updated_by": "U1234567",
"updated_timestamp": "1704067200",
"parent_record_id": "Rec12345678",
"fields": [
{
"key": "priority",
"column_id": "Col10000000",
"value": "OptHIGH123",
"select": [
"OptHIGH123"
]
},
{
"key": "completed",
"column_id": "Col10000001",
"value": false,
"checkbox": false
},
{
"key": "created_time",
"column_id": "Col10000002",
"value": 1704067200,
"timestamp": [
1704067200
]
}
]
}
}Create an item with all supported field types
{
"ok": true,
"item": {
"id": "Rec87654321",
"list_id": "F1234ABCD",
"date_created": 1704067200,
"created_by": "U1234567",
"updated_by": "U1234567",
"updated_timestamp": "1704067200",
"fields": [
{
"key": "assignee1",
"column_id": "Col01",
"value": "U1234567",
"user": [
"U1234567"
]
},
{
"key": "due_date",
"column_id": "Col02",
"value": "2024-12-31",
"date": [
"2024-12-31"
]
},
{
"key": "phone_number",
"column_id": "Col03",
"value": "+1-555-123-4567",
"phone": [
"+1-555-123-4567"
]
},
{
"key": "attachment1",
"column_id": "Col04",
"value": "F1234567890",
"attachment": [
"F1234567890"
]
},
{
"key": "description",
"column_id": "Col05",
"value": "[{\"type\":\"rich_text\",\"block_id\":\"def456\",\"elements\":[{\"type\":\"rich_text_section\",\"elements\":[{\"type\":\"text\",\"text\":\"Project description\"}]}]}]",
"text": "Project description",
"rich_text": [
{
"type": "rich_text",
"block_id": "def456",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Project description"
}
]
}
]
}
]
},
{
"key": "rating",
"column_id": "Col06",
"value": 4,
"rating": [
4
]
},
{
"key": "assignee2",
"column_id": "Col07",
"value": "U2345678",
"user": [
"U2345678"
]
},
{
"key": "attachment2",
"column_id": "Col08",
"value": "F2345678901",
"attachment": [
"F2345678901"
]
},
{
"key": "notes",
"column_id": "Col09",
"value": "[{\"type\":\"rich_text\",\"block_id\":\"ghi789\",\"elements\":[{\"type\":\"rich_text_section\",\"elements\":[{\"type\":\"text\",\"text\":\"Additional notes\"}]}]}]",
"text": "Additional notes",
"rich_text": [
{
"type": "rich_text",
"block_id": "ghi789",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Additional notes"
}
]
}
]
}
]
},
{
"key": "reviewer",
"column_id": "Col10",
"value": "U3456789",
"user": [
"U3456789"
]
},
{
"key": "reference_link",
"column_id": "Col11",
"value": "{\"originalUrl\":\"https:\\/\\/example.com\",\"attachment\":{\"https:\\/\\/example.com\":{\"fallback\":\"Example Website\",\"from_url\":\"https:\\/\\/example.com\\/\",\"service_name\":\"example.com\",\"service_icon\":\"https:\\/\\/example.com\\/favicon.ico\",\"title\":\"Example Website\",\"title_link\":\"https:\\/\\/example.com\\/\",\"text\":\"This is an example website for demonstration purposes.\",\"id\":1,\"original_url\":\"https:\\/\\/example.com\"}},\"displayAsUrl\":false,\"displayName\":\"Example Website\"}",
"link": [
{
"originalUrl": "https://example.com",
"attachment": {
"https://example.com": {
"fallback": "Example Website",
"from_url": "https://example.com/",
"service_name": "example.com",
"service_icon": "https://example.com/favicon.ico",
"title": "Example Website",
"title_link": "https://example.com/",
"text": "This is an example website for demonstration purposes.",
"id": 1,
"original_url": "https://example.com"
}
},
"displayAsUrl": false,
"displayName": "Example Website"
}
]
},
{
"key": "contact_email",
"column_id": "Col12",
"value": "contact@example.com",
"email": [
"contact@example.com"
]
},
{
"key": "related_message",
"column_id": "Col13",
"value": "https://yourteam.slack.com/archives/C1234567890/p1234567890123456",
"message": [
{
"value": "https://yourteam.slack.com/archives/C1234567890/p1234567890123456",
"channel_id": "C1234567890",
"ts": "1234567890.123456"
}
]
},
{
"key": "completed",
"column_id": "Col14",
"value": true,
"checkbox": true
},
{
"key": "budget",
"column_id": "Col15",
"value": 5000,
"number": [
5000
]
},
{
"key": "priority",
"column_id": "Col16",
"value": "OptHIGH123",
"select": [
"OptHIGH123"
]
},
{
"key": "approved",
"column_id": "Col17",
"value": false,
"checkbox": false
},
{
"key": "created_time",
"column_id": "Col18",
"value": 1704067200,
"timestamp": [
1704067200
]
}
]
}
}Create an item by duplicating an existing item
{
"ok": true,
"item": {
"id": "Rec99999999",
"list_id": "F1234ABCD",
"date_created": 1704067200,
"created_by": "U1234567",
"updated_by": "U1234567",
"updated_timestamp": "1704067200",
"fields": [
{
"key": "title",
"column_id": "Col10000000",
"value": "[{\"type\":\"rich_text\",\"block_id\":\"xyz789\",\"elements\":[{\"type\":\"rich_text_section\",\"elements\":[{\"type\":\"text\",\"text\":\"Copy of original task\"}]}]}]",
"text": "Copy of original task",
"rich_text": [
{
"type": "rich_text",
"block_id": "xyz789",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "Copy of original task"
}
]
}
]
}
]
},
{
"key": "assignee",
"column_id": "Col10000001",
"value": "U1234567",
"user": [
"U1234567"
]
},
{
"key": "priority",
"column_id": "Col10000002",
"value": "Opt456",
"select": [
"Opt456"
]
}
]
}
}Error when the specified list doesn't exist
{
"ok": false,
"error": "list_not_found"
}Error when the item to duplicate doesn't exist
{
"ok": false,
"error": "duplicated_item_not_found"
}Error when the list has reached its maximum number of items
{
"ok": false,
"error": "over_row_maximum"
}Error when field value type doesn't match column type
{
"ok": false,
"error": "invalid_input_type"
}Error when column_id doesn't exist in the list
{
"ok": false,
"error": "invalid_column_id"
}Error when too many values provided for a single field
{
"ok": false,
"error": "over_cell_fields_limit"
}Error when attachment file cannot be found
{
"ok": false,
"error": "file_not_found"
}Error when invalid value provided for vote column
{
"ok": false,
"error": "invalid_vote_value"
} This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.
| Error | Description |
|---|---|
list_not_found | The list was not found. |
over_row_maximum | Cannot create more items over the maximum. |
team_not_found | The team cannot be found. |
user_not_found | The user cannot be found. |
duplicated_item_not_found | The item to duplicate cannot be found. |
invalid_option_id | Option ID provided does not match column definition. |
invalid_args | The provided args are invalid. |
uneditable_column | Initial values provided for an uneditable column. |
invalid_input_type | The field value type does not match the column type. |
invalid_column_id | The column_id provided does not exist in the list. |
over_cell_fields_limit | Too many values provided for a single field. |
file_not_found | The attachment file could not be found. |
invalid_vote_value | Invalid value provided for a vote column. |
access_denied | Access to a resource specified in the request is denied. |
account_inactive | Authentication token is for a deleted user or workspace when using a |
deprecated_endpoint | The endpoint has been deprecated. |
ekm_access_denied | Administrators have suspended the ability to post a message. |
enterprise_is_restricted | The method cannot be called from an Enterprise. |
invalid_auth | Some aspect of authentication cannot be validated. Either the provided token is invalid or the request originates from an IP address disallowed from making the request. |
is_bot | This method cannot be called by a legacy bot. |
method_deprecated | The method has been deprecated. |
missing_scope | The token used is not granted the specific scope permissions required to complete this request. |
not_allowed_token_type | The token type used in this request is not allowed. |
not_authed | No authentication token provided. |
no_permission | The workspace token used in this request does not have the permissions necessary to complete the request. Make sure your app is a member of the conversation it's attempting to post a message to. |
org_login_required | The workspace is undergoing an enterprise migration and will not be available until migration is complete. |
token_expired | Authentication token has expired |
token_revoked | Authentication token is for a deleted user or workspace or the app has been removed when using a |
two_factor_setup_required | Two factor setup is required. |
team_access_not_granted | The token used is not granted the specific workspace access required to complete this request. |
accesslimited | Access to this method is limited on the current network |
fatal_error | The server could not complete your operation(s) without encountering a catastrophic error. It's possible some aspect of the operation succeeded before the error was raised. |
internal_error | The server could not complete your operation(s) without encountering an error, likely due to a transient issue on our end. It's possible some aspect of the operation succeeded before the error was raised. |
invalid_arg_name | The method was passed an argument whose name falls outside the bounds of accepted or expected values. This includes very long names and names with non-alphanumeric characters other than |
invalid_arguments | The method was either called with invalid arguments or some detail about the arguments passed is invalid, which is more likely when using complex arguments like blocks or attachments. |
invalid_array_arg | The method was passed an array as an argument. Please only input valid strings. |
invalid_charset | The method was called via a |
invalid_form_data | The method was called via a |
invalid_post_type | The method was called via a |
missing_post_type | The method was called via a |
ratelimited | The request has been ratelimited. Refer to the |
request_timeout | The method was called via a |
service_unavailable | The service is temporarily unavailable |
team_added_to_org | The workspace associated with your request is currently undergoing migration to an Enterprise Organization. Web API and other platform operations will be intermittently unavailable until the transition is complete. |
This table lists the expected warnings that this method will return. However, other warnings can be returned in the case where the service is experiencing unexpected trouble.
| Warning | Description |
|---|---|
missing_charset | The method was called via a |
superfluous_charset | The method was called via a |