Calendar Tools

Create Calendar Item

Create an appointment, task, visit, call, or WhatsApp calendar item. Requires title and either initial_date or relative_initial_date; initial_time defaults to 09:00 when a relative date has no time. Visits require a contact and property. If no responsible user is provided, assigns the requesting user. Write operation: creates a calendar item.

post/v1/mcp/tool/calendars

Request

  • Base URL: https://api.imobzi.app
  • URL: https://api.imobzi.app/v1/mcp/tool/calendars
  • Auth: API key in header X-Imobzi-Secret

Request body

titlestring required

Calendar item title (required).

initial_datestring nullable

Absolute start datetime in ISO 8601 format (YYYY-MM-DDTHH:MM:SS). The informed clock time is interpreted in America/Sao_Paulo, with or without a suffix. Use ONLY when the user provides an explicit date (e.g. '03/06/2026 às 9h'). For relative expressions ('amanhã', 'hoje', 'próxima segunda') use relative_initial_date + initial_time instead. Either initial_date OR relative_initial_date must be provided.

relative_initial_datestring nullable

Relative day/date expression for the start date. The backend resolves this deterministically using current date/time in America/Sao_Paulo (no LLM guessing). Preferred canonical values: today, tomorrow, day_after_tomorrow, next_monday, next_tuesday, next_wednesday, next_thursday, next_friday, next_saturday, next_sunday, next_week, end_of_week, end_of_month, next_month_same_day. Also accepts natural Portuguese expressions like: 'amanhã', 'depois de amanhã', 'próxima segunda', 'segunda-feira', 'semana que vem', 'fim do mês', 'daqui a 2 dias às 8h30'. Use together with initial_time when the time is not included in this expression.

initial_timestring nullable

Time component for the start datetime in HH:MM (24h) format. Use together with relative_initial_date. Examples: '09:00', '14:30', '8h' → '08:00', '9h' → '09:00'. If omitted, defaults to 09:00.

final_datestring

End datetime in ISO 8601 format, interpreted as an America/Sao_Paulo wall-clock value.

item_typestring

Calendar item type. Accepts the built-in values task, visit, call, or whatsapp, and active custom type names. Default: task. Visits require a contact and a property.

descriptionstring nullable

Optional calendar item description.

all_dayboolean nullable

Whether the item lasts all day.

doneboolean nullable

Whether the item is already completed.

status'active' | 'canceled' nullable

Optional status: active or canceled.

user_namestring nullable

Responsible user name. If neither user_name nor user_email is provided, the item is assigned to the requesting user.

user_emailstring nullable

Responsible user email (exact match, preferred for disambiguation). If neither user_email nor user_name is provided, the item is assigned to the requesting user.

contact_namestring nullable

Primary contact name for this item.

contact_emailstring nullable

Primary contact email (preferred).

contact_phonestring nullable

Primary contact phone number. Accepts flexible formatting with or without country code, area code, dashes and spaces.

contact_legal_identificationstring nullable

Primary contact legal identification (CPF or CNPJ).

property_codestring nullable

Related property code.

property_addressstring nullable

Related property address.

notification_bystring[] nullable

Notification channels: email and/or whatsapp.

show_observationsboolean nullable

Whether observations should be shown in communications.

deal_codestring nullable

Optional deal code to link, in numeric or prefixed format, such as 653 or VEN-653. For a numeric code, also provide pipeline_group_name.

pipeline_group_namestring nullable

Pipeline group name. Provide it when deal_code is numeric; omit it when the code already contains a pipeline prefix.

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.