Conventions

Every v3 endpoint follows the same rules for how data is written and read. They are collected here so that the endpoint pages can stay about their own resources.

JSON

• Send request bodies as JSON with Content-Type: application/json. That includes file uploads: a file's bytes travel base64-encoded inside the JSON body, never as a multipart form. See Task Fields and Files and Standalone Tasks. CSV imports are described on Data Sets.
• Property names are camelCase — templateKey, createdDateTime, hasMore.
• Responses are UTF-8 JSON with Content-Type: application/json; charset=utf-8.
• A property with no value is left out of a response rather than sent as null. A checklist with no due date has no due date property at all. Write your client to treat a missing property as "no value".
• Values that come from a fixed set, such as a checklist's status, are strings.
• A body that is not valid JSON is refused with 400 VALIDATION_ERROR and the message Invalid request body.

The same rules apply to what you send and what you receive, so you can read a resource, change a property and send it back.

Identifiers

Resources are identified by the value shown in their path parameter on each endpoint page:

Resource	Identifier	Example
Templates, checklists, tasks, fields, drafts, Data Sets and their fields, records and views, saved views	A GUID key	3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14
Webhook subscriptions	A GUID id	9a7e4c21-5b3d-4f08-8e6a-0c2d1f4b7e95
Members and groups	An integer id	1042
Schedules and schedule runs	An integer id	318
Comments and uploaded files	The id each list returns	—
Built-in Data Sets	A key, or the Data Set's slug	See Data Sets

Identifiers are opaque. Do not build them yourself or rely on their format beyond the type shown. A key in the wrong format is refused with 400 VALIDATION_ERROR naming the parameter; a well-formed key that matches nothing answers 404 with a code naming what was missing, such as CHECKLIST_NOT_FOUND.

Where a request refers to people, groups, tags or templates, it can often use a name or email address instead of an id. Those names are resolved against what the workspace actually contains — they are never created on the fly unless the endpoint says so. GET /v3/workspace returns every name a request can use.

Dates and Times

Every timestamp is a UTC instant in ISO 8601 format and ends in Z:

"createdDateTime": "2026-09-14T08:30:00Z"

When you send a date:

You send	It is read as
2026-09-30T17:00:00Z	17:00 UTC.
2026-09-30T17:00:00+01:00	The offset is honoured: 16:00 UTC.
2026-09-30T17:00:00	No offset, so it is taken as UTC: 17:00 UTC.

warning

A date without an offset is read as UTC, not as your local time. If you mean 5 pm in London, send 2026-09-30T17:00:00+01:00 or 2026-09-30T16:00:00Z.

Schedules are the exception. A schedule's startDateTime and a run's scheduledDateTime are wall-clock times in the schedule's own time zone, because a schedule that starts at 09:00 should start at 09:00 in winter and in summer. Each is reported beside the equivalent UTC instant. See Schedules.

Time Zones

Some writes record text with a date written into it — the activity entry a due date change leaves behind, for example. That text is written once, when the change is made, in a time zone chosen like this:

1. The X-CF-Timezone request header, if you send it.
2. Otherwise, the time zone of the member the key acts as, from their profile.
3. Otherwise — for a key that acts as the workspace — UTC.

PUT https://api.checkflow.io/v3/checklists/3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14/tasks/b81c55e0-2f4a-4d6b-a1e9-7c3d0f2e8a46/due-date
X-API-KEY: your-api-key-here
X-CF-Timezone: Europe/London

The header accepts IANA names such as Europe/London or America/New_York, and Windows names such as GMT Standard Time. An unknown zone is refused with 400 VALIDATION_ERROR and field set to X-CF-Timezone, rather than silently replaced, because activity text is written when the change is made and a wrong zone cannot be corrected afterwards.

The header never changes how the JSON timestamps themselves are written — they are always UTC — and it does not change activity that has already been recorded.

Partial Updates with PATCH

PATCH changes only what you send:

In the body	Effect
A property with a value	Sets it.
A property set to null	Clears it, where the property can be cleared — for example, removing a checklist's due date.
A property left out	Leaves it unchanged.

PATCH https://api.checkflow.io/v3/checklists/3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "name": "Invoice Review — INV-2041 (resubmitted)",
  "dueDate": null
}

This renames the checklist and removes its due date, and changes nothing else.

Template drafts go one step further and accept a full JSON Merge Patch (RFC 7386) of their document, where nested objects are merged too. Arrays in a merge patch always replace the whole array. See Template Drafts.

PUT replaces the whole of what it addresses — a task's assignees, a share setting, a saved view — with exactly what you send.

Request Ids

Every response, successful or not, carries an X-Request-Id header. Error bodies repeat it as requestId. It is the identifier to quote when you contact support, because it ties your request to our logs.

You can send your own X-Request-Id to have it used instead, so that your logs and ours name the same request. It is used when it is 1–128 characters long and contains only letters, digits and - _ . : + / =. Anything else is replaced with a generated id of the form req_ followed by 32 hex characters; the request itself is never refused because of it.

If the id you send is a GUID, the same GUID is also stamped on the background work the request causes, which helps support trace a problem end to end.

Empty Responses

A write that has nothing to return answers 204 No Content with no body. The endpoint pages say which do.

Related Pages

• Errors — what comes back when a request is refused.
• Pagination — how lists are paged and sorted.
• Idempotency — making a retried write safe.
• Workspace — every name a request can refer to, in one call.