Answer lists

An answer list is the set of answers a single_choice task requirement offers — Good / Worn / Damaged, for example. A list can be scored, so each answer also records a Result: pass, flag, fail or na. To use a list, pass its id as optionSetId when you add a requirement; see Task templates. Every field is listed on the operation’s page in the API Reference.

Operation	Request	Permission
listAnswerLists	GET /answer-lists	view_tasks
createAnswerList	POST /answer-lists	modify_tasks
updateAnswerList	PATCH /answer-lists/{id}	modify_tasks
archiveAnswerList	POST /answer-lists/{id}/archive	modify_tasks
restoreAnswerList	POST /answer-lists/{id}/restore	modify_tasks
duplicateAnswerList	POST /answer-lists/{id}/duplicate	modify_tasks
setAnswerListScoring	POST /answer-lists/{id}/scoring	modify_tasks
addAnswerListChoice	POST /answer-lists/{optionSetId}/choices	modify_tasks
reorderAnswerListChoices	POST /answer-lists/{optionSetId}/reorder-choices	modify_tasks
updateAnswerListChoice	PATCH /answer-list-choices/{id}	modify_tasks
removeAnswerListChoice	DELETE /answer-list-choices/{id}	modify_tasks

Paths are relative to your region’s base URL, for example https://api-us.suiteop.com/api/v1. See Authentication for permissions.

The API can’t delete a list. Archive it instead.

SuiteOp presets

Every organization has three preset lists: condition (Item Condition Check), cleanliness (Cleanliness Inspection) and working (Working Order Check). A preset’s preset field names it; a list your organization made has preset: null.

Presets can’t be edited. Renaming one, changing its rules, its scoring or any of its answers answers 403, with details.key validation.system_option_set_locked. You can still archive, restore and duplicate a preset. To customise one, duplicate it and edit the copy.

The Star rating list behind the star_rating shortcut is listed with preset: "star_rating". It is partly editable: you can change its answers’ Results, its default rules and logsElementCondition, and archive, restore or duplicate it. Its title and answer labels can’t be changed, and its answers can’t be added, removed or reordered; those calls answer 403 with validation.system_option_set_locked.

The lists behind the yes_no shortcut never appear in listAnswerLists and accept no changes at all — they can’t be archived or duplicated either.

Listing answer lists

GET /answer-lists returns every list in one array — it isn’t paginated. Archived lists are included with isArchived: true. Each list carries its answers in display order.

curl "https://api-us.suiteop.com/api/v1/answer-lists" \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": [
    {
      "id": "6a1f0c2e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
      "title": "Pool Check",
      "preset": null,
      "isGraded": true,
      "isArchived": false,
      "failRequiresPhoto": true,
      "failRequiresIssue": false,
      "flagRequiresPhoto": false,
      "flagRequiresIssue": false,
      "choices": [
        { "id": "0d9e8f7a-6b5c-4d3e-8f2a-1b0c9d8e7f6a", "label": "Clear", "result": "pass" },
        { "id": "1e0f9a8b-7c6d-4e5f-9a3b-2c1d0e9f8a7b", "label": "Cloudy", "result": "flag" },
        { "id": "2f1a0b9c-8d7e-4f6a-8b4c-3d2e1f0a9b8c", "label": "Green", "result": "fail" }
      ]
    }
  ],
  "meta": { "requestId": "3f1c9a52-…" }
}

title and label are the English text, or null when there is none. result is null on an unscored list.

Creating and copying a list

POST /answer-lists takes a title and answers 201 with { "id": "…" }. The new list is unscored and starts with three placeholder answers, Answer 1 to Answer 3. Read their ids with listAnswerLists, then rename, remove or add answers.

curl -X POST "https://api-us.suiteop.com/api/v1/answer-lists" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Pool Check" }'

POST /answer-lists/{id}/duplicate copies a list into a new one you can edit, and answers 200 with the new id. The copy keeps every answer in order with its Result, the scoring switch and the default rules, and its title gains (copy).

Default rules

On a scored list, four switches decide what a Fail or Flag answer demands before the task can complete: failRequiresPhoto, failRequiresIssue, flagRequiresPhoto and flagRequiresIssue. Change them, or the title, with PATCH /answer-lists/{id}; only the fields you send change. These four are defaults: a requirement copies them when it is bound to the list, so changing them later doesn’t change requirements already using it. A Result requires a photo or an issue, never both: turning one switch on turns its partner off (failRequiresIssue: true clears failRequiresPhoto), and if you send both on, the issue wins.

logsElementCondition: true records a completed, non-N/A answer on a requirement linked to a property element as that element’s condition check, building its history; see Property elements. Answering N/A, clearing the answer or undoing completion removes that requirement’s check. Only a scored list can turn it on: on an unscored list the call answers 400 with validation.log_requires_graded. Turning scoring off turns it off as well. listAnswerLists doesn’t return the setting. Unlike the four switches, it is not copied: an answer is logged according to the list’s current setting, so turning it off also stops new condition entries for requirements already using the list.

Editing answers

• Add — POST /answer-lists/{optionSetId}/choices with a label adds an answer at the end, and answers 201 with its id. On a scored list it must carry a result; on an unscored list it must not. On a list that awards points toward the task score, it must also carry points (0 to 999999.99, rounded to 2 decimals), except an N/A answer, which takes null; without them the call answers 400 with validation.points_required_every_choice. Don’t send points on a list without points: an organization that doesn’t have points turned on gets 403 with validation.task_points_disabled. A list that already has points keeps taking them either way. A duplicate of a list with points has points too. The API doesn’t show whether a list has points or let you turn them on or off.
• Change — PATCH /answer-list-choices/{id} with a label, a result or both. Send at least one.
• Remove — DELETE /answer-list-choices/{id} removes an answer permanently. The last answer of a list can’t be removed.
• Reorder — POST /answer-lists/{optionSetId}/reorder-choices with orderedIds: every answer id of the list exactly once, in the new order. A partial list, or an id from another list, is refused.

Edits and removals are refused on presets; see SuiteOp presets.

Scoring

POST /answer-lists/{id}/scoring turns scoring on or off for the whole list in one save.

• To turn it on, send isGraded: true and a results entry — { "choiceId", "result" } — for every current answer. It’s all or nothing: if any answer is missing a Result, nothing changes.
• To turn it off, send isGraded: false and results: []. Every answer’s Result is cleared.

curl -X POST "https://api-us.suiteop.com/api/v1/answer-lists/6a1f0c2e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/scoring" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "isGraded": true,
    "results": [
      { "choiceId": "0d9e8f7a-6b5c-4d3e-8f2a-1b0c9d8e7f6a", "result": "pass" },
      { "choiceId": "1e0f9a8b-7c6d-4e5f-9a3b-2c1d0e9f8a7b", "result": "flag" },
      { "choiceId": "2f1a0b9c-8d7e-4f6a-8b4c-3d2e1f0a9b8c", "result": "fail" }
    ]
  }'

Update, archive, restore, scoring, change, remove and reorder all answer { "success": true }. Like every response, these bodies arrive inside the envelope’s data.

Archiving

POST /answer-lists/{id}/archive stops a list being offered for new requirements; binding a requirement to an archived list is refused. Requirements already using it keep it. POST /answer-lists/{id}/restore makes it available again; restoring a list that isn’t archived changes nothing.