Deals Tools

Update Deal

Update a deal by numeric or prefixed code. Preserve complete prefixed codes such as VL-933; for numeric codes, also provide pipeline_group_name. Only provided fields are changed. Use stage_name to move the deal within its current pipeline group. Write operation: modifies a deal.

put/v1/mcp/tool/deal/{deal_code}

Request

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

Path parameters

deal_codestring required

Deal identifier to update. Required. Accepts a numeric code such as '653' or a complete prefixed code such as 'LOC-11' or 'VL-933'. Preserve the prefix and hyphen exactly as provided. Send the identifier in deal_code for this operation.

Request body

deal_codestring nullable

Deal identifier to update. Required. Accepts a numeric code such as '653' or a complete prefixed code such as 'LOC-11' or 'VL-933'. Preserve the prefix and hyphen exactly as provided. Send the identifier in deal_code for this operation.

pipeline_group_namestring nullable

Exact pipeline group display name used to identify the funnel. Provide it when deal_code is numeric, such as '653'. Omit it for a prefixed code such as 'VL-933', because the prefix resolves the pipeline group.

titlestring nullable

New title for the deal. Send only if the user wants to rename it. Example: 'Venda Apt 302 - Atualizado'.

valuenumber nullable

Updated monetary value in BRL. Plain number, dot as decimal separator, no currency symbols. Example values: 400000.00, 3500.50.

descriptionstring nullable

Updated notes or description for the deal. Replaces the existing description entirely (not appended). Example: 'Cliente renegociou valor para 450 mil'.

status'in progress' | 'win' | 'lost' | 'stagnant' | 'out_of_date' nullable

Change the deal status. Send one of the exact values below. Use exactly: 'in progress', 'win', 'lost', 'stagnant', 'out_of_date'. Translation map from Portuguese: em andamento / reabrir → 'in progress', ganho / ganhou / fechado → 'win', perdido / perdeu → 'lost', estagnado / parado → 'stagnant', atrasado / vencido → 'out_of_date'. When setting status='lost', also provide lost_reason and optionally lost_comment.

stage_namestring nullable

Move the deal to a different pipeline stage by name. The stage must exist within the deal's current pipeline group. Comparison ignores case, diacritics, and special characters. If the stage is not found, the tool returns valid stages for selection. Example values: 'Proposta Enviada', 'Fechamento'.

interest'buy' | 'rent' | 'vacation_rental' nullable

Change the deal interest type. Send one of the exact slugs. Translation: compra→'buy', aluguel→'rent', temporada→'vacation_rental'. If changing to 'vacation_rental', also provide vacation_start and vacation_end.

vacation_startstring nullable

Start date of the vacation rental period. Provide it when interest='vacation_rental'. Format: ISO 8601 datetime. Example: '2026-12-01T00:00:00.000Z'.

vacation_endstring nullable

End date of the vacation rental period. Provide it when interest='vacation_rental'. Must be after vacation_start. Format: ISO 8601 datetime. Example: '2026-12-15T00:00:00.000Z'.

favoriteboolean nullable

Mark (true) or unmark (false) the deal as a favorite. Favorites are highlighted in the UI for quick access. Send true to favorite, false to unfavorite.

lost_reasonstring nullable

Reason the deal was lost. Only relevant when status='lost'. Should be a short label describing why (e.g. 'Preço acima do mercado', 'Cliente desistiu', 'Escolheu concorrente'). Ignored if status is not 'lost'.

lost_commentstring nullable

Additional free-text comment explaining why the deal was lost. Complements lost_reason with more detail. Only relevant when status='lost'. Example: 'O cliente encontrou um imóvel mais barato na região'.

date_closestring nullable

Expected or actual closing date of the deal. Format: YYYY-MM-DD (date only, no time). Use for forecasting or to record when a deal was closed. Example: '2026-06-15'.

user_namestring nullable

Responsible broker name or partial name. The lookup is case-insensitive and considers active users. It must resolve to exactly one user; otherwise the tool returns options for disambiguation. Omit both user_name and user_email to keep or assign the requesting user, depending on the operation. Examples: 'Maria', 'Carlos Souza'.

user_emailstring nullable

Responsible broker email. Exact match, case-insensitive. Preferred when available because it avoids ambiguity for duplicated names. Omit both user_email and user_name to keep the current responsible broker.

Response

Successful Response

unknown required

Changes

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