Create a new task - Welcome 👋

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

curl -X POST 'https://api.vambe.ai/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

{
  "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

const createSimpleTask = async (title, description, responsibleId) => {
  const response = await fetch('https://api.vambe.ai/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

const createTaskWithDeadline = async (
  title,
  description,
  dueDate,
  dueTime,
  timezone,
  responsibleId,
) => {
  const response = await fetch('https://api.vambe.ai/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

const createContactTask = async (
  contactId,
  title,
  description,
  responsibleId,
) => {
  const response = await fetch('https://api.vambe.ai/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

const createTeamTask = async (title, description, responsibleIds, priority) => {
  const response = await fetch('https://api.vambe.ai/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

const createAllDayTask = async (title, description, dueDate, responsibleId) => {
  const response = await fetch('https://api.vambe.ai/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

// 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.ai/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

{
  "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

Status Configuration: Tasks are automatically assigned the initial status configuration - no need to specify it
Responsible Users: Validate that all responsibleIds are valid and active users
Timezone Handling: Always specify timezone when using due dates with specific times
Description Length: Keep descriptions concise but informative (500-1000 characters recommended)
Priority Assignment: Use priority strategically - “0” (low), “1” (medium), “2” (high)
All-Day Tasks: For all-day tasks, omit dueTime or set it to null
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

GET /api/public/tasks - Get tasks by filters
PUT /api/public/tasks/ - Update a task
DELETE /api/public/tasks/ - Delete a task
GET /api/public/team-members/all - 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

Body

application/json

title

string

required

Minimum string length: 1

description

string | null

required

dueDate

string | null

required

dueTime

string | null

required

timezone

string | null

required

responsibleIds

string[]

required

aiContactId

string | null

required

aiCustomerId

string | null

required

priority

enum<string>

required

Available options:

0,

1,

2

Response

Task created successfully

The response is of type object.

Task Management

​Overview

​Use Cases

​Authentication

​Request Body

​Priority Values

​Response Structure

​Task Object

​Example Request

​Example Response

​Common Use Cases

​1. Create a Simple Task

​2. Create Task with Due Date

​3. Create Task Associated with Contact

​4. Create Task with Multiple Assignees

​5. Create All-Day Task

​6. Automated Task Creation from Webhook

​Validation Rules

​Title

​Status Configuration

​Responsible IDs

​Priority

​Due Date

​Due Time

​Timezone

​AI Contact ID

​AI Customer ID

​Description

​Error Responses

​Common Validation Errors

​Best Practices

​Performance Tips

​Related Endpoints

​Notes

Body

Response

Overview

Use Cases

Authentication

Request Body

Priority Values

Response Structure

Task Object

Example Request

Example Response

Common Use Cases

1. Create a Simple Task

2. Create Task with Due Date

3. Create Task Associated with Contact

4. Create Task with Multiple Assignees

5. Create All-Day Task

6. Automated Task Creation from Webhook

Validation Rules

Title

Status Configuration

Responsible IDs

Priority

Due Date

Due Time

Timezone

AI Contact ID

AI Customer ID

Description

Error Responses

Common Validation Errors

Best Practices

Performance Tips

Related Endpoints

Notes