Skip to content
Documentation · Checklists

API reference

Checklists

Resource checklists

A checklist is a list of task groups, each with tasks or an illustration picture. Properly assigns a taskId to every task; completed-job webhooks report by that id.

Create a checklist

POST /v1/checklists 201 Created x-api-key

Creates a checklist for a property. The response carries server-assigned ids: each task group has a taskGroupId and each task comes back as { label, sourceTaskId, taskId }. Persist the taskId mapping: completed-job webhooks report task completion by taskId.

Request body
Field Type Required Notes
title string Required —
propertyId string One of One of propertyId or sourcePropertyId identifies the property.
sourcePropertyId string One of Your property id.
description string Optional —
taskGroups object[] Required Non-empty. See Task group.

Task group

A task group carries exactly one of sourcePictureUrl or tasks. Sending both fails validation with the message "The sourcePictureUrl field can only be set if the field tasks is not provided."

Task group
Field Type Required Notes
title string Required —
sourceTaskGroupId string Optional Min 3 chars. Create only.
verificationRequired boolean Optional —
sourcePictureUrl string One of An illustration image URL for the group. Exactly one of sourcePictureUrl or tasks. Create only.
tasks object[] One of Non-empty. See Task. Required on update.

Task

Task
Field Type Required Notes
sourceTaskId string Optional Min 3 chars.
label string Required 3–500 chars.
curl 
curl -X POST https://platform.getproperly.com/v1/checklists \
  -H "x-api-key: $PROPERLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Turnover clean",
    "sourcePropertyId": "pms-100234",
    "taskGroups": [
      {
        "title": "Kitchen",
        "sourceTaskGroupId": "pms-tg-kitchen",
        "verificationRequired": true,
        "tasks": [
          { "sourceTaskId": "pms-task-101", "label": "Empty dishwasher" },
          { "sourceTaskId": "pms-task-102", "label": "Wipe counters" }
        ]
      },
      {
        "title": "Balcony layout",
        "sourcePictureUrl": "https://cdn.example.com/standards/balcony.jpg"
      }
    ]
  }'

Update a checklist

PATCH /v1/checklists/{checklistId} 200 OK x-api-key

When taskGroups is present the whole step structure is replaced and every taskGroupId and taskId is re-minted; re-sync the mapping from the response. In update payloads every group must carry tasks (sourcePictureUrl-only groups are create-only) and groups take no sourceTaskGroupId.

Request body
Field Type Required Notes
title string Optional —
description string Optional —
taskGroups object[] Optional Replaces the step structure. Each group: title, verificationRequired?, tasks (required).
Request 
curl -X PATCH https://platform.getproperly.com/v1/checklists/chk_9RtV \
  -H "x-api-key: $PROPERLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskGroups": [
      {
        "title": "Kitchen",
        "tasks": [
          { "sourceTaskId": "pms-task-101", "label": "Empty dishwasher" },
          { "sourceTaskId": "pms-task-103", "label": "Restock coffee pods" }
        ]
      }
    ]
  }'

Disable a checklist

POST /v1/checklists/{checklistId}/disable 200 OK x-api-key

No body. Disables the checklist; existing jobs keep their copies.

Request 
curl -X POST https://platform.getproperly.com/v1/checklists/chk_9RtV/disable \
  -H "x-api-key: $PROPERLY_API_KEY"

List a property's checklists

GET /v1/properties/{propertyId}/checklists 200 OK x-api-key

Returns every checklist on the property in the collection envelope, each task group with its taskGroupId and each task as { label, sourceTaskId, taskId }. Unpaginated: nextCursor is always null and hasMore always false. This is the authoritative way to recover a lost mapping.

curl 
curl https://platform.getproperly.com/v1/properties/8jL2mQxT4a/checklists \
  -H "x-api-key: $PROPERLY_API_KEY"

Type to search the Platform API docs.