Update task - Welcome 👋

Overview

Update an existing task by its ID. All fields are optional - only include the fields you want to update. The task can be updated to change its title, description, status, assignees, due date, priority, or associated entities. Use this endpoint to modify task details, reassign tasks, update completion status, or adjust deadlines.

Use Cases

Task Status Updates: Mark tasks as complete or change their workflow status
Reassignment: Transfer tasks between team members
Deadline Management: Adjust due dates and times as priorities shift
Priority Changes: Update task priority based on changing business needs
Content Updates: Modify task title or description
Association Updates: Link or unlink tasks from contacts/customers

Authentication

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

x-api-key: your_api_key_here

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	The UUID of the task to update

Request Body

All fields are optional. Only include the fields you want to update:

Field	Type	Required	Description
`title`	string	No	Task title (minimum 1 character)
`description`	string \| null	No	Detailed description of the task
`newStatusPosition`	number	No	Update status by position in the status configuration (alternative to newStatusName)
`newStatusName`	string	No	Update status by name (e.g., “Pendiente”, “En Progreso”) (alternative to newStatusPosition)
`dueDate`	string \| null	No	Due date (ISO 8601 format: YYYY-MM-DD or full datetime). Set to null to remove due date
`dueTime`	string \| null	No	Due time (HH:MM format, e.g., “14:30”)
`timezone`	string \| null	No	Timezone for due date (e.g., “America/Santiago”)
`responsibleIds`	string[]	No	Array of user IDs to assign as responsible (replaces all existing assignees)
`aiContactId`	string \| null	No	Associated contact ID
`aiCustomerId`	string \| null	No	Associated customer ID
`priority`	string	No	Task priority: “0” (low), “1” (medium), or “2” (high)

Note: To update the task status, use either newStatusPosition or newStatusName. You cannot use both at the same time.

Response Structure

Returns the updated 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 - Mark Task as Complete

curl -X PUT 'https://api.vambe.ai/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "newStatusName": "Completado"
  }'

Alternative using position:

curl -X PUT 'https://api.vambe.ai/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "newStatusPosition": 3
  }'

Example Request - Update Multiple Fields

curl -X PUT 'https://api.vambe.ai/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Updated: Follow up with customer",
    "description": "Updated description with new information",
    "dueDate": "2025-10-26T15:00:00.000Z",
    "dueTime": "15:00",
    "timezone": "America/Santiago",
    "priority": "2",
    "responsibleIds": ["228d7a0d-9072-4ca8-939b-959b75cc606a", "338e8b1e-8183-5db9-a4ab-a6ab86dd717b"]
  }'

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated: Follow up with customer",
  "description": "Updated description with new information",
  "due_timezone": "America/Santiago",
  "due_at": "2025-10-26T15:00:00.000Z",
  "is_all_day": false,
  "created_at": "2025-10-20T10: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"
    },
    {
      "responsible_id": "338e8b1e-8183-5db9-a4ab-a6ab86dd717b"
    }
  ],
  "status_config": {
    "id": "status-uuid-789",
    "name": "Pendiente",
    "color": "#60a5fa",
    "type": "initial",
    "order": 1
  }
}

Common Use Cases

1. Mark Task as Complete

const completeTask = async (taskId, completedStatusName) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusName: completedStatusName,
      }),
    },
  );

  return await response.json();
};

// Example usage - using status name
const completedTask = await completeTask(
  '123e4567-e89b-12d3-a456-426614174000',
  'Completado',
);

// Alternative - using status position
const completeTaskByPosition = async (taskId, statusPosition) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusPosition: statusPosition,
      }),
    },
  );

  return await response.json();
};

2. Reassign Task to Different User

const reassignTask = async (taskId, newResponsibleId) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        responsibleIds: [newResponsibleId],
      }),
    },
  );

  return await response.json();
};

// Example usage
const reassignedTask = await reassignTask(
  '123e4567-e89b-12d3-a456-426614174000',
  'new-agent-uuid',
);

3. Update Task Priority

const updateTaskPriority = async (taskId, newPriority) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        priority: newPriority, // "0", "1", or "2"
      }),
    },
  );

  return await response.json();
};

// Example usage
const urgentTask = await updateTaskPriority(
  '123e4567-e89b-12d3-a456-426614174000',
  '2', // High priority
);

4. Extend Task Deadline

const extendDeadline = async (taskId, newDueDate, newDueTime, timezone) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        dueDate: newDueDate,
        dueTime: newDueTime,
        timezone: timezone,
      }),
    },
  );

  return await response.json();
};

// Example usage - Extend by 2 days
const extendedTask = await extendDeadline(
  '123e4567-e89b-12d3-a456-426614174000',
  '2025-10-28T14:00:00.000Z',
  '14:00',
  'America/Santiago',
);

5. Add Additional Team Members

const addTeamMembers = async (taskId, currentResponsibleIds, newMemberIds) => {
  const allResponsibleIds = [...currentResponsibleIds, ...newMemberIds];

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        responsibleIds: allResponsibleIds,
      }),
    },
  );

  return await response.json();
};

// Example usage
const updatedTask = await addTeamMembers(
  '123e4567-e89b-12d3-a456-426614174000',
  ['existing-agent-uuid-1'],
  ['new-agent-uuid-2', 'new-agent-uuid-3'],
);

6. Update Task Description

const updateTaskDescription = async (taskId, newDescription) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        description: newDescription,
      }),
    },
  );

  return await response.json();
};

// Example usage
const updatedTask = await updateTaskDescription(
  '123e4567-e89b-12d3-a456-426614174000',
  'Updated with additional context from meeting notes',
);

7. Link Task to Contact

const linkTaskToContact = async (taskId, contactId) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        aiContactId: contactId,
      }),
    },
  );

  return await response.json();
};

// Example usage
const linkedTask = await linkTaskToContact(
  '123e4567-e89b-12d3-a456-426614174000',
  'contact-uuid-789',
);

8. Bulk Update Task Status

const bulkUpdateTaskStatus = async (taskIds, newStatusName) => {
  const updatePromises = taskIds.map((taskId) =>
    fetch(`https://api.vambe.ai/api/public/tasks/${taskId}`, {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusName: newStatusName,
      }),
    }).then((res) => res.json()),
  );

  return await Promise.all(updatePromises);
};

// Example usage - Mark multiple tasks as complete
const completedTasks = await bulkUpdateTaskStatus(
  ['task-uuid-1', 'task-uuid-2', 'task-uuid-3'],
  'Completado',
);

Validation Rules

Task ID

Required: Yes (in URL path)
Format: Valid UUID
Note: Task must exist and belong to your organization

Title

Required: No (only if updating)
Minimum length: 1 character (if provided)
Type: String

Status Updates

You can update the task status using one of two methods: Option 1: By Status Name

Field: newStatusName
Type: String
Example: “Pendiente”, “En Progreso”, “Completado”
Note: Must match an existing status name in your organization

Option 2: By Status Position

Field: newStatusPosition
Type: Number
Example: 0, 1, 2, 3
Note: Represents the position/order of the status in your status configuration

Important: You can only use one method at a time - either newStatusName OR newStatusPosition, not both.

Responsible IDs

Required: No (only if updating)
Type: Array of strings (UUIDs)
Note: Must be valid user IDs from your organization
Note: Replaces all existing assignees (not additive)

Priority

Required: No (only if updating)
Type: String
Allowed values: “0” (low), “1” (medium), “2” (high)
Note: The value is sent as a string but stored as an integer (0, 1, or 2)

Error Responses

Status Code	Description
400	Bad Request - Invalid task ID or request body
401	Unauthorized - Invalid or missing API key
404	Not Found - Task not found or invalid references
500	Internal Server Error - Something went wrong

Common Error Examples

{
  "statusCode": 404,
  "message": "Task not found"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "priority",
      "message": "Priority must be one of: low, medium, high"
    }
  ]
}

Best Practices

Partial Updates: Only send the fields you want to update - no need to send the entire object
Responsible IDs: When updating responsibleIds, include ALL users who should be assigned (it replaces, not appends)
Status Updates: Use newStatusName or newStatusPosition to update status - don’t use both at the same time
Status Validation: Verify the status name/position exists in your organization before updating
Optimistic UI: Update UI optimistically and rollback on error for better user experience
Timezone Consistency: When updating due dates, always include timezone for accuracy
Remove Due Date: Set dueDate to null to remove the due date from a task
Priority Format: Use “0”, “1”, or “2” for priority (not “low”, “medium”, “high”)
Audit Trail: Consider logging updates for compliance and debugging
Concurrent Updates: Be aware of potential race conditions when multiple users update the same task

Performance Tips

Batch Updates: Group related updates into a single request when possible
Conditional Updates: Check if the value actually changed before making an API call
Error Handling: Implement retry logic with exponential backoff for transient failures
Validation: Validate data on the client side before making API calls

Important Notes

Immutable Fields: Some fields like id, created_at, and creator_id cannot be updated
Organization Scoped: You can only update tasks that belong to your organization
Permission Based: Users may need appropriate permissions to update certain tasks
Status Update Methods: Use either newStatusName OR newStatusPosition, not both
Cascading Effects: Changing status may trigger automated actions or notifications
Responsible IDs Replacement: The responsibleIds array replaces all existing assignees - it does not add to them
Remove Due Date: Set dueDate to null to remove the due date from a task
Priority Format: Priority is sent as a string (“0”, “1”, “2”) but returned as an integer (0, 1, 2) in the response

GET /api/public/tasks - Get tasks by filters
POST /api/public/tasks - Create a new task
DELETE /api/public/tasks/ - Delete a task
GET /api/public/team-members/all - Get team members for assignment

Webhook Events

Updating a task may trigger webhook events such as:

task.updated - When any task field is updated
task.completed - When task status changes to completed
task.reassigned - When responsible users change

Configure webhooks to receive real-time notifications of task updates.

Path Parameters

string<uuid>

required

The UUID of the task to update

Body

application/json

title

string

Minimum length: 1

description

string | null

dueDate

string | null

dueTime

string | null

timezone

string | null

responsibleIds

string[]

aiContactId

string | null

aiCustomerId

string | null

priority

enum<string>

Available options:

0,

1,

2

newStatusPosition

number

newStatusName

string

Response

Task updated successfully

The response is of type object.

Task Management

​Overview

​Use Cases

​Authentication

​Path Parameters

​Request Body

​Response Structure

​Task Object

​Example Request - Mark Task as Complete

​Example Request - Update Multiple Fields

​Example Response

​Common Use Cases

​1. Mark Task as Complete

​2. Reassign Task to Different User

​3. Update Task Priority

​4. Extend Task Deadline

​5. Add Additional Team Members

​6. Update Task Description

​7. Link Task to Contact

​8. Bulk Update Task Status

​Validation Rules

​Task ID

​Title

​Status Updates

​Responsible IDs

​Priority

​Error Responses

​Common Error Examples

​Best Practices

​Performance Tips

​Important Notes

​Related Endpoints

​Webhook Events

Path Parameters

Body

Response

Overview

Use Cases

Authentication

Path Parameters

Request Body

Response Structure

Task Object

Example Request - Mark Task as Complete

Example Request - Update Multiple Fields

Example Response

Common Use Cases

1. Mark Task as Complete

2. Reassign Task to Different User

3. Update Task Priority

4. Extend Task Deadline

5. Add Additional Team Members

6. Update Task Description

7. Link Task to Contact

8. Bulk Update Task Status

Validation Rules

Task ID

Title

Status Updates

Responsible IDs

Priority

Error Responses

Common Error Examples

Best Practices

Performance Tips

Important Notes

Related Endpoints

Webhook Events