Raise a property task

A connection can create a task at an existing property and read its progress later. For example, a repair-reporting form could raise a maintenance task without you retyping the report.

Decide what should become a task

Read these Letted guides first:
https://app.letted.com/docs/property-tasks
https://app.letted.com/docs/api-reference

If you cannot open them, ask me to paste the pages rather than guessing.

When a repair report arrives in [my other system], prepare a Letted task
at the matching property. Use the report as the description and write a
short, clear title. Ask me how to choose the priority and due date.
Keep the report's external reference and avoid duplicate tasks on retries.

Use View properties and rooms to find the property, Create property tasks to create the task, and View tasks to check its progress.

Example request

Send POST /api/v1/tasks with a JSON body, bearer key and idempotency key. This fictional example uses a placeholder property ID.

{
  "propertyId": "11111111-1111-4111-8111-111111111111",
  "externalId": "repair-report-508",
  "title": "Check the dripping kitchen tap",
  "description": "The tenant reports a steady drip from the kitchen tap. Please arrange a check through the normal task process.",
  "category": "Maintenance",
  "priority": "Medium",
  "dueDate": "2027-02-10"
}

Required: propertyId and title. Optional: description, category, priority, dueDate and externalId.

Categories are Inspection, Maintenance, Legal, Tenant and Other. Priorities are Low, Medium, High and Urgent. If omitted, category is Other and priority is Medium. The due date uses YYYY-MM-DD.

What happens next

A successful request returns HTTP 201, the task under data and an operationId for follow-up setup. The task starts with API status InProgress and follows Letted's task behaviour. Plan setup happens afterwards; do not create a second task if that setup needs attention.

Creating a task does not mean work has been carried out or a contractor has been booked. This API does not provide contractor assignment, task completion or purchasing actions.

Check progress

Read the task with:

GET /api/v1/tasks/TASK_ID

The response includes title, description, property ID, category, priority, status, due date, created/updated dates and a link to open the task in Letted.

API status values are Pending, InProgress, Blocked, WaitingTenant, WaitingContractor, Completed and Archived.

For automatic updates, subscribe to task.created and task.status_changed. Use the event's category to select Maintenance tasks. A status-change event lets you follow both completion and reopening; do not assume a completed task can never change again.

See Receive updates from Letted for the event format and an important difference in how task statuses are written in events.