--- title: "Create a task" method: POST path: "/v1/projects/{project_id}/tasks" tags: ["Task"] --- # Create a task `POST /v1/projects/{project_id}/tasks` ## Request - Base URL: `https://api.telerivet.com` - URL: `https://api.telerivet.com/v1/projects/{project_id}/tasks` - Auth: one of: - HTTP basic - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`) Creates and starts an asynchronous task that is applied to all entities matching a filter (e.g. contacts, messages, or data rows). Tasks are designed to efficiently process a large number of entities. When processing a large number of entities, tasks are much faster than using the API to query and loop over all objects matching a filter. Several different types of tasks are supported, including applying services to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV. When using a task to apply a Custom Actions or Cloud Script API service (`apply_service_to_contacts`, `apply_service_to_rows`, or `apply_service_to_messages`), the `task` variable will be available within the service. The service can use custom variables on the task object (e.g. `task.vars.example`), such as to store aggregate statistics for the rows matching the filter. ## Path parameters - `project_id` string, required ## Request body - object - `task_type` string, required: Type of task to create. Each `task_type` applies to a certain type of entity (such as a contact, message, or data row). Tasks for contacts: - update_contact_var - add_group_members - remove_group_members - set_conversation_status - set_send_blocked - apply_service_to_contacts - delete_contacts - export_contacts Tasks for data rows: - update_row_var - apply_service_to_rows - delete_rows - export_rows Tasks for messages: - cancel_messages - resend_messages - retry_message_services - apply_service_to_messages - add_label - remove_label - update_message_var - delete_messages - export_messages - `task_params` object: Parameters applied to all matching rows (specific to `task_type`). **apply_service_to_contacts**, **apply_service_to_messages**, **apply_service_to_rows**: - service_id - The ID of the service to apply (string) - variables - Optional object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like [[$name]] (with a leading $ character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like $name (with a leading $ character). (object)
**update_contact_var**, **update_message_var**, **update_row_var**: - variable - The custom variable name (string) - value - The value to set (string, boolean, float, null)
**add_group_members**, **remove_group_members**: - group_id - The ID of the group (string)
**add_label**, **remove_label**: - label_id - The ID of the label (string)
**resend_messages**: - route_id - ID of the new route to use, or null to use the original route (string)
**set_send_blocked**: - send_blocked - true to block sending messages, false to unblock sending messages (boolean)
**set_conversation_status**: - conversation_status - "active", "handled", or "closed" (string)
**export_contacts**, **export_messages**, **export_rows**: - storage_id - ID of a storage provider where the CSV file will be saved. (string) Currently only AWS S3 is supported as a storage provider. This requires creating a S3 bucket in your own AWS account, as well as an IAM user with access key and secret that has permission to write to that bucket. You can configure your own S3 bucket as a storage provider on the [Storage Providers](https://telerivet.com/dashboard/a/storage) page. Direct downloads are not supported when exporting data via the API. (string) - filename - Path within the storage backend where the CSV file will be saved - column_ids - IDs of columns to save in the CSV file. If not provided, all default columns will be saved. (array of strings, optional)
**delete_contacts**, **delete_messages**, **delete_rows**, **cancel_messages**, **retry_message_services**:
No parameters. - `filter_type` 'query_contacts' | 'contact_ids' | 'query_rows' | 'row_ids' | 'query_messages' | 'message_ids', required: Type of filter defining the rows that the task is applied to. Each `filter_type` queries a certain type of entity (such as contacts, messages, or data rows). In general, the `task_type` and the `filter_type` must return the same type of entity; however, tasks applied to contacts (other than `export_contacts`) can also be applied when the filter returns entities that are associated with a contact, such as messages or data rows. (Note that in this case, it is possible for the task to be applied multiple times to an individual contact if multiple messages or data rows are associated with the same contact.) - `filter_params` object, required: Parameters defining the rows that the task is applied to (specific to `filter_type`). **`query_contacts`**:
The same filter parameters as used by project.queryContacts. If you want to apply the task to all contacts, use the parameters {"all": true}. **`contact_ids`**: - `contact_ids` - IDs of up to 100 contacts to apply this task to (array of strings) **`query_messages`**:
The same filter parameters as used by project.queryMessages. If you want to apply the task to all messages, use the parameters {"all": true}. **`message_ids`**: - `message_ids` - IDs of up to 100 messages to apply this task to (array of strings) **`query_rows`**:
The same filter parameters as used by table.queryRows. If you want to apply the task to all rows in the table, use the parameters {"all": true}. **`row_ids`**: - `row_ids` - IDs of up to 100 data rows to apply this task to (array of strings) - `table_id` string: ID of the data table this task is applied to (if applicable). Required if filter_type is `query_rows` or `row_ids`. - `vars` object: Initial custom variables to set for the task. If the task applies a service, the service can read and write custom variables on the task object (e.g. `task.vars.example`), such as to store aggregate statistics for the rows matching the filter. ## Response `200` Successful response - Task: Represents an asynchronous task that is applied to all entities matching a filter. Tasks include services applied to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV. - `id` string: ID of the task - `task_type` string: The task type - `task_params` object: Parameters applied to all matching rows (specific to `task_type`). See project.createTask. - `filter_type` string: Type of filter defining the rows that the task is applied to - `filter_params` object: Parameters defining the rows that the task is applied to (specific to `filter_type`). See project.createTask. - `time_created` integer: Time the task was created in Telerivet - `time_active` integer, nullable: Time Telerivet started executing the task - `time_complete` integer, nullable: Time Telerivet finished executing the task - `total_rows` integer, nullable: The total number of rows matching the filter (null if not known) - `current_row` integer, nullable: The number of rows that have been processed so far - `status` 'created' | 'queued' | 'active' | 'complete' | 'failed' | 'cancelled': The current status of the task - `error_message` string, nullable: Error message if the task failed - `vars` object: Custom variables stored for this task. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. - `table_id` string: ID of the data table this task is applied to (if applicable) - `user_id` string: ID of the Telerivet user who created the task (if applicable) - `project_id` string: ID of the project this task belongs to ## Other responses - `400`: Invalid request parameters - `401`: Invalid or missing API key or Bearer token - `404`: Resource not found --- [API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)