> ## Documentation Index > Fetch the complete documentation index at: https://docs.attio.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a task > Creates a new task. At present, tasks can only be created from plaintext without record reference formatting. Required scopes: `task:read-write`, `object_configuration:read`, `record_permission:read`, `user_management:read`. ## OpenAPI ````yaml https://api.attio.com/openapi/api post /v2/tasks openapi: 3.1.0 info: title: Attio API version: 2.0.0 contact: name: Attio Support email: support@attio.com url: https://attio.com/help servers: - url: https://api.attio.com description: Production security: - oauth2: [] tags: - name: Objects description: >- Objects are the core data models inside of Attio. They contain standard objects, such as [people](/rest-api/endpoint-reference/standard-objects/people/list-person-records), [companies](/rest-api/endpoint-reference/standard-objects/companies/list-company-records) or [deals](/docs/standard-objects-deals), and custom objects that are specific to your use-case. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Object views description: Object views are saved table or board layouts for an object. - name: List views description: List views are saved table or board layouts for a list. - name: Attributes description: >- Attributes model properties of objects and lists. Some attributes, such as the `name` attribute on a person, are system-defined, while others are user-defined. Attributes are one of [many types](/docs/attribute-types) such as text, location or select. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Records description: >- Records are individual instances of objects e.g. a specific [person](/rest-api/endpoint-reference/standard-objects/people/list-person-records) or [company](/rest-api/endpoint-reference/standard-objects/companies/list-company-records). See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: SCIM groups description: >- SCIM groups represent Attio teams managed through the SCIM provisioning protocol. - name: SCIM schemas description: >- SCIM schemas describe the resource types supported by the SCIM service provider. - name: SCIM users description: >- SCIM users represent workspace members managed through the SCIM provisioning protocol. - name: Lists description: >- Lists are used to model a particular process. A list contains many records of a single object type, where each record is represented by an entry. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Meta description: Meta endpoints are used to get information about the API token. - name: Entries description: >- Entries are elements in a list that reference a single parent record. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Files description: >- Files are documents and folders linked to records, stored either in Attio or connected via external storage providers. - name: Workspace members description: >- Workspace members represent a user with access to a workspace. Workspace members are assigned roles that determine what they can do within the workspace. - name: Notes description: Notes are rich text documents that reference a single parent record. - name: Meetings description: >- Meetings are events synced from your calendar, added manually or added from third-party integrations. - name: Call recordings description: >- Call recordings store video, audio, transcript and speaker information for calls. They are linked to meetings. - name: Transcripts description: >- Transcripts contain the speech segments and speaker information for a call recording. They are linked to call recordings. - name: Tasks description: >- A task is a defined, actionable item with references to linked records and assigned workspace members. - name: Webhooks description: >- Webhooks allow you to listen for changes to data in Attio, for example when a record is updated. - name: Threads description: >- Threads are groups of [comments](/rest-api/endpoint-reference/comments/get-a-comment) on either a record or entry. - name: Comments description: >- Comments are messages on a [thread](/rest-api/endpoint-reference/threads/list-threads). - name: People description: >- People are one of the core objects inside of Attio. Person records can be added to lists and can be created automatically when syncing your mailbox. - name: Companies description: >- Companies are one of the core objects inside of Attio. Company records can be added to lists and can be created automatically when syncing your mailbox. - name: Users description: >- Users are an optional standard object that represents a user of your system. Users can belong to many workspaces. - name: Deals description: >- Deals are an optional standard object that represent a deal or opportunity. - name: Workspaces description: >- Workspaces are an optional standard object that represent a workspace or account in your system. Workspaces have many users and can be used to model a multi-tenant system. A company record can optionally have multiple workspaces. paths: /v2/tasks: post: tags: - Tasks summary: Create a task description: >- Creates a new task. At present, tasks can only be created from plaintext without record reference formatting. Required scopes: `task:read-write`, `object_configuration:read`, `record_permission:read`, `user_management:read`. requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: content: type: string maxLength: 2000 description: >- The text content of the task, in the format specified by the `format` property. A max length of 2000 characters is enforced. example: Follow up on current software solutions format: type: string enum: - plaintext description: >- The format of the task content to be created. Rich text formatting, links and @references are not supported. deadline_at: type: - string - 'null' description: The deadline of the task, in ISO 8601 format. example: '2023-01-01T15:00:00.000000000Z' is_completed: type: boolean description: Whether the task has been completed. example: false linked_records: type: array description: >- Records linked to the task. Records can be linked by domain (for companies), email address (for people), record ID (for all objects) or by a unique matching attribute (for all objects). Creating record links within task content text is not possible via the API at present. anyOf: - type: array description: >- An array of email addresses and/or company website domains. Email addresses are matched to person records via the `email_addresses` attribute; domains are matched to company records via the `domains` attribute. example: - person@company.com - fundstack.com items: type: string description: An email address or company website domain. example: person@company.com - type: array items: anyOf: - type: object properties: target_object: type: string example: people description: >- The ID or slug of the parent object the tasks refers to. This can reference both standard and custom objects.` target_record_id: type: string format: uuid description: >- The ID of the parent record the task refers to. example: 891dcbfc-9141-415d-9b2a-2238a6cc012d required: - target_object - target_record_id - type: object example: target_object: people matching_attribute_id_123: - value: matching_attribute_id_123 properties: target_object: type: string description: >- A UUID or slug to identify the object that the referenced record belongs to. example: people '[slug_or_id_of_matching_attribute]': type: array description: >- In addition to referencing records directly by record ID, you may also reference by a matching attribute of your choice. For example, if you want to add a reference to the person record with email "alice@website.com", you should pass a value with `target_object` set to `"people"` and `email_addresses` set to `[{email_address:"alice@website.com"}]`. The key should be the slug or ID of the matching attribute you would like to use and the value should be an array containing a single value of the appropriate attribute type (as specified below). Matching on multiple values is not currently supported. Matching attributes must be unique. This process is similar to how you use the `matching_attribute` query param in Attio's [assert endpoints](/rest-api/endpoint-reference/records/assert-a-record). items: anyOf: - type: object properties: domain: type: string description: The full domain of the website. example: app.attio.com - type: object properties: email_address: type: string description: An email address string example: alice@app.attio.com - type: object properties: value: type: number example: 17224912 description: Numbers are persisted as 64 bit floats. - type: object properties: original_phone_number: type: string example: '07234172834' description: >- The raw, original phone number, as inputted. country_code: type: - string - 'null' enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - AN - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - SS - RS - SC - SL - SG - SK - SI - SB - SO - ZA - GS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - BQ - KP - SX - XK - AC example: GB description: >- The ISO 3166-1 alpha-2 country code representing the country that this phone number belongs to. - type: object properties: value: type: string description: >- A raw text field. Values are limited to 10MB. required: - target_object - '[slug_or_id_of_matching_attribute]' assignees: type: array items: anyOf: - type: object properties: referenced_actor_type: type: string enum: - workspace-member description: >- The actor type of the task assignee. Only `workspace-member` actors can be assigned to tasks. [Read more information on actor types here](/docs/actors). example: workspace-member referenced_actor_id: type: string format: uuid description: The ID of the actor assigned to this task. example: 50cf242c-7fa3-4cad-87d0-75b1af71c57b required: - referenced_actor_type - referenced_actor_id - type: object properties: workspace_member_email_address: type: string description: >- Workspace member actors can be referenced by email address as well as actor ID. example: alice@attio.com required: - workspace_member_email_address additionalProperties: false description: Workspace members assigned to this task. required: - content - format - deadline_at - is_completed - linked_records - assignees required: - data responses: '200': description: Success content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/task' required: - data description: Success '400': description: Bad Request content: application/json: schema: type: object properties: status_code: type: number enum: - 400 type: type: string enum: - invalid_request_error code: type: string enum: - validation_type message: type: string example: Only standard or custom object records can be linked to. required: - status_code - type - code - message description: Bad Request '404': description: Not Found content: application/json: schema: type: object properties: status_code: type: number enum: - 404 type: type: string enum: - invalid_request_error code: type: string enum: - not_found message: type: string example: Object with slug/ID "people" not found. required: - status_code - type - code - message description: Not Found security: - oauth2: - task:read-write - object_configuration:read - record_permission:read - user_management:read components: schemas: task: type: object properties: id: type: object properties: workspace_id: type: string format: uuid description: The ID of the workspace the task belongs to. example: 14beef7a-99f7-4534-a87e-70b564330a4c task_id: type: string format: uuid description: The ID of the task. example: 649e34f4-c39a-4f4d-99ef-48a36bef8f04 required: - workspace_id - task_id content_plaintext: type: string description: >- The plaintext representation of the task content. Inline linked records will appear as "@record name" and are returned in the `linked_records` property. example: Follow up on current software solutions deadline_at: type: - string - 'null' description: The deadline date of the task. Returned as an ISO 8601 timestamp. example: '2023-01-01' is_completed: type: boolean description: Whether the task has been completed. example: false completed_at: type: - string - 'null' description: When the task was completed, or null if it has not been completed. example: '2022-11-21T13:22:49.061281000Z' linked_records: type: array items: type: object properties: target_object_id: type: string description: >- The ID of the parent object the task refers to. At present, only `people` and `companies` are supported. example: people target_record_id: type: string format: uuid description: The ID of the parent record the task refers to. example: 891dcbfc-9141-415d-9b2a-2238a6cc012d required: - target_object_id - target_record_id description: >- Records linked to the task. Creating record links within task content text is not possible via the API at present. assignees: type: array items: type: object properties: referenced_actor_type: type: string enum: - api-token - workspace-member - system - app description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: workspace-member referenced_actor_id: type: string format: uuid description: The ID of the workspace member actor assigned to this task. example: 50cf242c-7fa3-4cad-87d0-75b1af71c57b required: - referenced_actor_type - referenced_actor_id description: Workspace members assigned to this task. created_by_actor: type: object description: The actor that created this task. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b created_at: type: string description: When the task was created. example: '2022-11-21T13:22:49.061281000Z' required: - id - content_plaintext - deadline_at - is_completed - completed_at - linked_records - assignees - created_by_actor - created_at securitySchemes: oauth2: type: oauth2 description: This API uses OAuth 2.0 with the authorization code grant flow. flows: authorizationCode: authorizationUrl: https://app.attio.com/authorize tokenUrl: https://app.attio.com/oauth/token scopes: user_management:read: View workspace members. user_management:read-write: View workspace members. record_permission:read: View, and optionally write, records. record_permission:read-write: View, and optionally write, records. object_configuration:read: >- View, and optionally write, the configuration and attributes of objects. object_configuration:read-write: >- View, and optionally write, the configuration and attributes of objects. list_entry:read: View, and optionally write, the entries in a list. list_entry:read-write: View, and optionally write, the entries in a list. list_configuration:read: >- View, and optionally write, the configuration and attributes of lists. list_configuration:read-write: >- View, and optionally write, the configuration and attributes of lists. public_collection:read: >- View, and optionally write, both the settings and information within public collections. public_collection:read-write: >- View, and optionally write, both the settings and information within public collections. private_collection:read: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. private_collection:read-write: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. comment:read: View comments (and threads), and optionally write comments. comment:read-write: View comments (and threads), and optionally write comments. task:read: View, and optionally write, tasks. task:read-write: View, and optionally write, tasks. note:read: View, and optionally write, notes. note:read-write: View, and optionally write, notes. meeting:read: View, and optionally write, meetings. meeting:read-write: View, and optionally write, meetings. call_recording:read: >- View, and optionally write, call recordings, transcripts and speakers for meetings. call_recording:read-write: >- View, and optionally write, call recordings, transcripts and speakers for meetings. webhook:read: View, and optionally manage, webhooks. webhook:read-write: View, and optionally manage, webhooks. file:read: View, and upload files. file:read-write: View, and upload files. ````