> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new task

> Creates a new task for the authenticated user. The task can be associated with a contact or customer, and assigned to one or more responsible users. Due dates can be specified with optional time and timezone information.

## Overview

Create a new task and assign it to one or more team members. Tasks can be associated with contacts or customers, include due dates with timezone support, and have customizable priorities and statuses.

Use this endpoint to programmatically create tasks from your application, integrate with external systems, or automate task creation based on specific triggers.

## Use Cases

* **Automated Task Creation**: Create tasks automatically when certain events occur (e.g., new lead, customer inquiry)
* **CRM Integration**: Sync tasks from external CRM systems to Vambe
* **Follow-up Management**: Automatically create follow-up tasks after customer interactions
* **Workflow Automation**: Create tasks as part of automated workflows
* **API Integrations**: Allow external applications to create tasks in Vambe
* **Mobile Apps**: Enable task creation from mobile applications

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Request Body

| Field            | Type                    | Required | Description                                                                                                        |
| ---------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `title`          | string                  | Yes      | Task title (minimum 1 character)                                                                                   |
| `description`    | string \| null          | No       | Detailed description of the task                                                                                   |
| `dueDate`        | ISO 8601 string \| null | No       | Due date in ISO 8601 format (e.g., "2025-11-26" or "2025-11-26T00:00:00.000Z")                                     |
| `dueTime`        | HH:mm string \| null    | No       | Due time in 24-hour format (e.g., "14:30", "09:00"). If omitted, task is marked as all-day                         |
| `timezone`       | IANA timezone \| null   | No       | IANA Time Zone identifier (e.g., "America/Santiago", "Europe/London", "UTC"). Required when `dueTime` is specified |
| `responsibleIds` | string\[] (UUID)        | Yes      | Array of user UUIDs to assign as responsible                                                                       |
| `aiContactId`    | string (UUID) \| null   | No       | Associated contact UUID                                                                                            |
| `aiCustomerId`   | string (UUID) \| null   | No       | Associated customer UUID                                                                                           |
| `priority`       | "0" \| "1" \| "2"       | Yes      | Task priority: "0" (low), "1" (medium), or "2" (high)                                                              |

### Priority Values

* `"0"` - Low priority task
* `"1"` - Medium priority task
* `"2"` - High priority task

**Note**: The task will automatically be assigned the initial status configuration from your organization. You don't need to provide a status ID when creating tasks via the public API.

## Response Structure

Returns the created task object:

### Task Object

| Field                   | Type           | Description                                          |
| ----------------------- | -------------- | ---------------------------------------------------- |
| `id`                    | string (UUID)  | Unique identifier for the task                       |
| `title`                 | string         | Task title                                           |
| `description`           | string         | Detailed description of the task                     |
| `due_timezone`          | string \| null | Timezone for the due date (e.g., "America/Santiago") |
| `due_at`                | string \| null | Due date and time (ISO 8601 format)                  |
| `is_all_day`            | boolean        | Whether the task is an all-day task                  |
| `created_at`            | string         | Task creation date (ISO 8601 format)                 |
| `ai_contact_id`         | string \| null | Associated contact ID if applicable                  |
| `ai_customer_id`        | string \| null | Associated customer ID if applicable                 |
| `task_status_config_id` | string (UUID)  | ID of the status configuration                       |
| `priority`              | number         | Task priority: 0 (low), 1 (medium), or 2 (high)      |
| `creator_id`            | string (UUID)  | ID of the user who created the task                  |
| `task_responsibles`     | array          | Array of responsible user objects                    |
| `status_config`         | object \| null | Custom status configuration object                   |

## Example Request

```bash theme={null}
curl -X POST 'https://api.vambe.me/api/public/tasks' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Follow up with customer",
    "description": "Call customer regarding their inquiry about pricing",
    "dueDate": "2025-10-25T14:00:00.000Z",
    "dueTime": "14:00",
    "timezone": "America/Santiago",
    "responsibleIds": ["228d7a0d-9072-4ca8-939b-959b75cc606a"],
    "aiContactId": "contact-uuid-123",
    "aiCustomerId": null,
    "priority": "2"
  }'
```

## Example Response

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Follow up with customer",
  "description": "Call customer regarding their inquiry about pricing",
  "due_timezone": "America/Santiago",
  "due_at": "2025-10-25T14:00:00.000Z",
  "is_all_day": false,
  "created_at": "2025-10-23T10:30:00.000Z",
  "ai_contact_id": "contact-uuid-123",
  "ai_customer_id": null,
  "task_status_config_id": "status-uuid-789",
  "priority": 2,
  "creator_id": "user-uuid-456",
  "task_responsibles": [
    {
      "responsible_id": "228d7a0d-9072-4ca8-939b-959b75cc606a"
    }
  ],
  "status_config": {
    "id": "status-uuid-789",
    "name": "Pendiente",
    "color": "#60a5fa",
    "type": "initial",
    "order": 1
  }
}
```

## Common Use Cases

### 1. Create a Simple Task

```javascript theme={null}
const createSimpleTask = async (title, description, responsibleId) => {
  const response = await fetch('https://api.vambe.me/api/public/tasks', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title,
      description,
      dueDate: null,
      dueTime: null,
      timezone: null,
      responsibleIds: [responsibleId],
      aiContactId: null,
      aiCustomerId: null,
      priority: '1', // Medium priority
    }),
  });

  return await response.json();
};

// Example usage
const task = await createSimpleTask(
  'Review proposal',
  'Review and approve the client proposal',
  'agent-uuid-123',
);
```

### 2. Create Task with Due Date

```javascript theme={null}
const createTaskWithDeadline = async (
  title,
  description,
  dueDate,
  dueTime,
  timezone,
  responsibleId,
) => {
  const response = await fetch('https://api.vambe.me/api/public/tasks', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title,
      description,
      dueDate,
      dueTime,
      timezone,
      responsibleIds: [responsibleId],
      aiContactId: null,
      aiCustomerId: null,
      priority: '2', // High priority
    }),
  });

  return await response.json();
};

// Example usage - Create task due tomorrow at 2 PM
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);

const urgentTask = await createTaskWithDeadline(
  'Client presentation',
  'Prepare and deliver quarterly presentation',
  tomorrow.toISOString(),
  '14:00',
  'America/Santiago',
  'agent-uuid-123',
);
```

### 3. Create Task Associated with Contact

```javascript theme={null}
const createContactTask = async (
  contactId,
  title,
  description,
  responsibleId,
) => {
  const response = await fetch('https://api.vambe.me/api/public/tasks', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title,
      description,
      dueDate: null,
      dueTime: null,
      timezone: null,
      responsibleIds: [responsibleId],
      aiContactId: contactId,
      aiCustomerId: null,
      priority: '1', // Medium priority
    }),
  });

  return await response.json();
};

// Example usage
const contactTask = await createContactTask(
  'contact-uuid-456',
  'Follow up on inquiry',
  'Customer asked about premium features',
  'agent-uuid-123',
);
```

### 4. Create Task with Multiple Assignees

```javascript theme={null}
const createTeamTask = async (title, description, responsibleIds, priority) => {
  const response = await fetch('https://api.vambe.me/api/public/tasks', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title,
      description,
      dueDate: null,
      dueTime: null,
      timezone: null,
      responsibleIds,
      aiContactId: null,
      aiCustomerId: null,
      priority,
    }),
  });

  return await response.json();
};

// Example usage - Assign to multiple team members
const teamTask = await createTeamTask(
  'Quarterly planning',
  'Prepare Q4 strategic plan',
  ['agent-uuid-1', 'agent-uuid-2', 'agent-uuid-3'],
  '2', // High priority
);
```

### 5. Create All-Day Task

```javascript theme={null}
const createAllDayTask = async (title, description, dueDate, responsibleId) => {
  const response = await fetch('https://api.vambe.me/api/public/tasks', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title,
      description,
      dueDate,
      dueTime: null, // No time = all-day task
      timezone: null,
      responsibleIds: [responsibleId],
      aiContactId: null,
      aiCustomerId: null,
      priority: '1', // Medium priority
    }),
  });

  return await response.json();
};

// Example usage
const allDayTask = await createAllDayTask(
  'Team workshop',
  'Annual team building workshop',
  '2025-11-15T00:00:00.000Z',
  'agent-uuid-123',
);
```

### 6. Automated Task Creation from Webhook

```javascript theme={null}
// Webhook handler that creates tasks automatically
const handleWebhook = async (webhookData) => {
  // When a new high-value lead comes in, create a follow-up task
  if (webhookData.event === 'lead.created' && webhookData.lead.value > 10000) {
    const dueDate = new Date();
    dueDate.setHours(dueDate.getHours() + 2); // Due in 2 hours

    const response = await fetch('https://api.vambe.me/api/tasks', {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        title: `Follow up: High-value lead - ${webhookData.lead.name}`,
        description: `New lead worth $${webhookData.lead.value}. Contact within 2 hours.`,
        dueDate: dueDate.toISOString(),
        dueTime: dueDate.toTimeString().slice(0, 5),
        timezone: 'America/Santiago',
        responsibleIds: [webhookData.lead.assignedAgent],
        aiContactId: webhookData.lead.contactId,
        aiCustomerId: null,
        priority: '2', // High priority
      }),
    });

    return await response.json();
  }
};
```

## Validation Rules

### Title

* **Required**: Yes
* **Minimum length**: 1 character
* **Type**: String

### Status Configuration

* **Required**: No
* **Note**: Tasks are automatically assigned the initial status configuration from your organization. You don't need to provide a status ID when creating tasks via the public API.

### Responsible IDs

* **Required**: Yes
* **Type**: Array of UUID strings
* **Format**: Valid UUID v4 identifiers (e.g., `"228d7a0d-9072-4ca8-939b-959b75cc606a"`)
* **Note**: Must be valid user IDs from your organization
* **Minimum**: At least one user ID required

### Priority

* **Required**: Yes
* **Type**: Enum string (`"0"` | `"1"` | `"2"`)
* **Allowed values**:
  * `"0"` - Low priority
  * `"1"` - Medium priority
  * `"2"` - High priority
* **Note**: The value is sent as a string but transformed and stored as an integer (0, 1, or 2) in the response

### Due Date

* **Required**: No
* **Type**: ISO 8601 date string or null
* **Format**: `YYYY-MM-DD` or full ISO 8601 datetime (e.g., `2025-11-26T00:00:00.000Z`)
* **Examples**: `"2025-10-25"`, `"2025-10-25T14:00:00.000Z"`
* **Note**: Internally transformed to a Date object

### Due Time

* **Required**: No
* **Type**: Time string in HH:mm format or null
* **Format**: 24-hour time format `HH:mm`
* **Examples**: `"14:30"`, `"09:00"`, `"23:59"`
* **Note**: If omitted or null, the task is marked as an all-day task (`is_all_day: true`)

### Timezone

* **Required**: No (but recommended when `dueTime` is specified)
* **Type**: IANA Time Zone identifier string or null
* **Format**: Standard IANA timezone database identifier
* **Examples**: `"America/Santiago"`, `"Europe/London"`, `"Asia/Tokyo"`, `"UTC"`
* **Note**: Used to correctly interpret the due date and time. Defaults to `"UTC"` if not provided

### AI Contact ID

* **Required**: No
* **Type**: UUID string or null
* **Format**: Valid UUID v4 identifier
* **Note**: Links the task to a specific contact in your organization

### AI Customer ID

* **Required**: No
* **Type**: UUID string or null
* **Format**: Valid UUID v4 identifier
* **Note**: Links the task to a specific customer in your organization

### Description

* **Required**: No
* **Type**: String or null
* **Note**: Detailed description of the task

## Error Responses

| Status Code | Description                                             |
| ----------- | ------------------------------------------------------- |
| 400         | Bad Request - Invalid request body or validation failed |
| 401         | Unauthorized - Invalid or missing API key               |
| 404         | Not Found - Invalid statusId or responsibleIds          |
| 500         | Internal Server Error - Something went wrong            |

### Common Validation Errors

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "title",
      "message": "Title must be at least 1 character"
    },
    {
      "field": "priority",
      "message": "Priority must be one of: \"0\", \"1\", \"2\""
    },
    {
      "field": "dueTime",
      "message": "Invalid time format. Expected HH:mm (e.g., \"14:30\")"
    }
  ]
}
```

## Best Practices

1. **Status Configuration**: Tasks are automatically assigned the initial status configuration - no need to specify it
2. **Responsible Users**: Validate that all responsibleIds are valid and active users
3. **Timezone Handling**: Always specify timezone when using due dates with specific times
4. **Description Length**: Keep descriptions concise but informative (500-1000 characters recommended)
5. **Priority Assignment**: Use priority strategically - "0" (low), "1" (medium), "2" (high)
6. **All-Day Tasks**: For all-day tasks, omit dueTime or set it to null
7. **Contact Association**: Link tasks to contacts when possible for better context and tracking

## Performance Tips

* **Batch Creation**: If creating multiple tasks, consider implementing retry logic
* **Validation**: Validate data on the client side before making API calls
* **Error Handling**: Implement proper error handling for failed task creation
* **Async Processing**: For bulk task creation, consider queuing and processing asynchronously

## Related Endpoints

* [GET /api/public/tasks](/reference/tasks/get-tasks) - Get tasks by filters
* [PUT /api/public/tasks/{id}](/reference/tasks/update-task) - Update a task
* [DELETE /api/public/tasks/{id}](/reference/tasks/delete-task) - Delete a task
* [GET /api/public/team-members/all](/reference/team-members/get-all-team-members) - Get team members for assignment

## Notes

* **Automatic Timestamps**: created\_at is automatically set to the current time
* **Default Status**: New tasks are automatically assigned the initial status configuration from your organization
* **Creator Tracking**: The creator\_id is automatically set based on the authenticated user
* **Organization Scoped**: Tasks are automatically associated with your organization
* **Interactive Notes**: Tasks associated with contacts will automatically create interactive notes
* **Priority Format**: Priority is sent as a string ("0", "1", "2") but returned as an integer (0, 1, 2) in the response


## OpenAPI

````yaml post /api/public/tasks
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/tasks:
    post:
      tags:
        - tasks
      summary: Create a new task
      description: >-
        Creates a new task for the authenticated user. The task can be
        associated with a contact or customer, and assigned to one or more
        responsible users. Due dates can be specified with optional time and
        timezone information.
      operationId: TaskPublicController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskPublicDto'
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseDto'
        '400':
          description: >-
            Invalid request body - Check that all required fields are provided
            and valid
        '401':
          description: Unauthorized - Invalid or missing authentication token
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseDto'
components:
  schemas:
    CreateTaskPublicDto:
      type: object
      properties:
        title:
          type: string
          minLength: 1
        description:
          type: string
          nullable: true
        dueDate:
          type: string
          nullable: true
        dueTime:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        responsibleIds:
          type: array
          items:
            type: string
        aiContactId:
          type: string
          nullable: true
        aiCustomerId:
          type: string
          nullable: true
        priority:
          type: string
          enum:
            - '0'
            - '1'
            - '2'
        associateToCalendar:
          default: false
          type: boolean
      required:
        - title
        - description
        - dueDate
        - dueTime
        - timezone
        - responsibleIds
        - aiContactId
        - aiCustomerId
        - priority
    TaskResponseDto:
      type: object
      properties: {}

````