SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester
Tasks

Create a task. Values are validated and refused with a 400 that names the field: priority must be one of the listed values, due_at must be an ISO 8601 date-time, max_score and weight cannot be negative, allowed_submission_count and required_files must be whole numbers of 0 or more, and a title is at most 300 characters. Unknown fields are refused

POSThttps://app.softsolz.uk/api/v1/services/tasks/tasks

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

titlestringrequired

Task title (required, trimmed).

instructionsstring

What the assignee has to do.

category_idinteger

Category to file this under.

prioritystring

Urgency. Defaults to normal.

statusstring

Defaults to draft. Only published tasks are visible to assignees.

due_atstring

Default deadline.

schedule_modestring

Defaults to one_time. A recurring task is a definition and is never assigned directly; its occurrences are separate tasks.

starts_atstring

When a scheduled task opens.

submission_modestring

What must come back. Defaults to file_and_text.

required_filesinteger

Minimum files per submission.

allowed_submission_countinteger | null

Attempt cap; null means unlimited resubmissions.

allow_late_submissionboolean

Allow submitting past the deadline.

required_fieldsarray of strings

Ids of custom fields the assignee must fill in.

grading_schemestring

Overrides the category scheme. Omit to inherit.

max_scorenumber

Denominator for numeric schemes.

weightnumber

Weight in the category rollup. Defaults to 1.

rubricarray of objects

Criteria for the rubric scheme.

checklistarray of objects

Steps the assignee ticks off.

custom_fieldsobject

Values for workspace-defined fields.

type_idinteger | null

Task type from GET /types. Its defaults fill fields you leave out.

tagsobject | null

Tags to put on the task, up to 20. Names that do not exist yet are created.

org_unit_idinteger | null

Department or location from GET /org-units.

project_idinteger | null

Project the task belongs to. Refused with 400 project_not_found when it does not exist or the caller cannot see it.

milestone_idinteger | null

Milestone of that project. Refused with 422 milestone_not_in_project when it belongs to another project.

assignment_modestring

How the work is shared out. It cannot change once people have the work.

assignment_planobject

For mode shared: { required } is how many people must finish.

requires_acceptanceboolean

People must accept the work before it counts as theirs.

instructions_htmlstring | null

Formatted instructions, up to 50 KB. Only simple formatting and http, https and mailto links are kept.

impactinteger | null

Impact from 1 to 5.

urgencyinteger | null

Urgency from 1 to 5.

riskstring | null

Risk level.

estimate_minutesinteger | null

Expected effort in minutes.

budget_centsinteger | null

Budget in the smallest unit of cost_currency.

actual_cost_centsinteger | null

Cost so far in the smallest unit of cost_currency.

cost_currencystring | null

Three letter currency code for the budget and cost.

external_refstring | null

Your own reference for the task, up to 120 characters. Searchable.

Response

Response Body

idintegerTask id.
category_idinteger | nullCategory this task belongs to.
titlestringTask title.
instructionsstring | nullWhat the assignee has to do.
prioritystringUrgency of the work.
statusstringTask lifecycle, separate from assignment status. Paused hides the task from assignees; cancelled cascades to open assignments.
due_atstring | nullDefault deadline, overridable per assignment.
schedule_modestringone_time exists once, scheduled starts at starts_at, recurring is a definition that generates occurrences.
starts_atstring | nullWhen a scheduled task becomes visible to assignees.
submission_modestringWhat the assignee must send back.
required_filesintegerMinimum number of files a submission must carry.
allowed_submission_countinteger | nullMaximum attempts; null means unlimited resubmissions.
allow_late_submissionbooleanWhether work may still be submitted after the deadline.
grading_schemestring | nullOverrides the category scheme; null inherits it.
max_scorenumber | nullDenominator for points, percentage and letter schemes.
weightnumberWeight of this task in its category rollup. Defaults to 1.
rubricarray of objectsCriteria for the rubric scheme: { id, label, max_score, weight }.
checklistarray of objectsSteps the assignee ticks off: { id, label, required, requires_note, requires_file }.
attachmentsarray of objectsReference material supplied with the task.
custom_fieldsobjectValues for the workspace-defined fields on this task.
sourcestringWhere the task came from: manual, api, form, chat, webhook, appointment, template, schedule, outreach or seo.
template_idinteger | nullThe template this task was created from.
template_namestring | nullThe name of the template this task was created from.
assignment_countintegerHow many people this task is assigned to.
created_atstringCreation timestamp.
updated_atstringRound-trip as expected_updated_at to guard against stale writes.

Request

curl --request POST \
--url https://app.softsolz.uk/api/v1/services/tasks/tasks \
--header 'Authorization: Bearer sk_live_your_key' \
--header 'Content-Type: application/json' \
--data '{
"title": "Quarterly safety inspection",
"instructions": "Walk every floor.",
"priority": "high",
"status": "published",
"due_at": "2026-09-01T17:00:00.000Z",
"schedule_mode": "one_time",
"starts_at": null,
"submission_mode": "file_and_text",
"required_files": 1,
"allowed_submission_count": 3,
"allow_late_submission": true,
"required_fields": [
"inspection_type"
],
"grading_scheme": "percentage",
"max_score": 100,
"weight": 2,
"rubric": [
{
"id": "accuracy",
"label": "Accuracy",
"max_score": 40
}
],
"checklist": [
{
"id": "floor-1",
"label": "Floor 1 complete",
"required": true
}
],
"custom_fields": {},
"tags": {
"tag_ids": [
7
],
"names": [
"Follow up"
]
},
"assignment_mode": "independent",
"assignment_plan": {
"required": 2
},
"requires_acceptance": false,
"instructions_html": "<p>Check <strong>every</strong> door.</p>",
"impact": 3,
"urgency": 4,
"estimate_minutes": 90,
"budget_cents": 25000,
"actual_cost_cents": 12000,
"cost_currency": "GBP",
"external_ref": "JOB-1182"
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
"data": {
"id": 42,
"category_id": 7,
"title": "Quarterly safety inspection",
"instructions": "Walk every floor and photograph each extinguisher.",
"priority": "high",
"status": "published",
"due_at": "2026-09-01T17:00:00.000Z",
"schedule_mode": "one_time",
"starts_at": null,
"submission_mode": "file_and_text",
"required_files": 1,
"allowed_submission_count": 3,
"allow_late_submission": true,
"grading_scheme": null,
"max_score": 100,
"weight": 2,
"rubric": [
{
"id": "accuracy",
"label": "Accuracy",
"max_score": 40,
"weight": 1
}
],
"checklist": [
{
"id": "floor-1",
"label": "Floor 1 complete",
"required": true
}
],
"attachments": [
{
"filename": "report.pdf",
"mime": "application/pdf",
"size_bytes": 184320,
"download_url": "https://s3.eu-west-2.amazonaws.com/...",
"content_url": "/api/services/tasks/files/content?key=tasks%2F..."
}
],
"custom_fields": {
"property": "Riverside House",
"inspection_type": "annual"
},
"source": "api",
"template_id": null,
"template_name": null,
"assignment_count": 12,
"created_at": "2026-08-01T09:00:00.000Z",
"updated_at": "2026-08-02T11:15:00.000Z"
}
}