Skip to main content

Getting Started with the API

This walkthrough takes you from a new API key to a completed task in five requests. It uses curl, but every request is plain HTTP and JSON, so any language works the same way.

By the end you will have started an Invoice Review checklist, answered a field on its first task and completed that task.

Before You Start​

  • You need an Administrator to create an API key, or to be one.
  • You need a template to run. The examples use one called Invoice Review; use any template in your workspace.

Step 1: Create an API Key​

  1. Open the Team page and select the API & Integrations tab.
  2. Click Create API Key.
  3. Name it Getting started, and under Acts as choose yourself.
  4. Click Create API Key and copy the key.

Store the key in an environment variable so it stays out of your shell history and your code:

export CHECKFLOW_API_KEY="your-api-key-here"

On Windows PowerShell, use $env:CHECKFLOW_API_KEY = "your-api-key-here".

Step 2: Check the Key​

curl https://api.checkflow.io/v3/auth/test \
  -H "X-API-KEY: $CHECKFLOW_API_KEY"
{
  "status": "ok",
  "teamId": "6c1d2f0a-93b4-4e7d-a8f2-51c0de7b9a33",
  "teamName": "Acme Corp",
  "region": "US",
  "isEnterprise": true,
  "apiKey": {
    "name": "Getting started",
    "createdDateTime": "2026-09-14T08:02:11Z",
    "actsAs": {
      "type": "member",
      "id": 1042,
      "email": "sarah.chen@acme.example",
      "name": "Sarah Chen",
      "role": "Administrator"
    }
  }
}

Check two things:

  • teamName is the workspace you expect.
  • region is US. If it is EU, your workspace is served from https://api-eu.checkflow.io — use that address for the rest of this walkthrough. (If you sent the request to the wrong address, you already know: the answer is 421 with the right address in url.)

If you get 401, the error.code says why. See Authentication Errors.

Step 3: Find a Template​

curl https://api.checkflow.io/v3/templates \
  -H "X-API-KEY: $CHECKFLOW_API_KEY"
{
  "items": [
    {
      "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
      "name": "Invoice Review",
      "description": "Check, approve and pay a supplier invoice.",
      "version": 1,
      "isArchived": false,
      "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
      "createdDateTime": "2026-09-14T09:12:44.107Z"
    }
  ],
  "hasMore": false,
  "total": 1
}

Copy the key of the template you want to run. Keys are how v3 refers to templates, checklists, tasks and fields. See Templates.

Step 4: Start a Checklist​

curl https://api.checkflow.io/v3/checklists \
  -H "X-API-KEY: $CHECKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e2a41-5d3b-4f86-9a0e-1b2c3d4e5f60" \
  -d '{
        "templateKey": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "name": "Invoice Review — INV-2041"
      }'

The Idempotency-Key makes the request safe to retry: if the connection drops, send it again with the same key and you get the same checklist back rather than a second one. Use a new key for each new checklist. See Idempotency.

The answer is 201 Created and the whole checklist, including every task and field. Shortened:

{
  "allTasksComplete": false,
  "tasks": [
    {
      "assignees": [],
      "fields": [
        {
          "key": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73",
          "name": "Invoice Number",
          "type": "ShortText",
          "isRequired": true,
          "value": ""
        }
      ],
      "comments": [],
      "key": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
      "name": "Check the invoice details",
      "order": 1,
      "isHeading": false,
      "status": "Incomplete",
      "isComplete": false,
      "isNotApplicable": false,
      "isCurrentlyHalted": false,
      "isCurrentlyHidden": false,
      "isAssignedExclusively": false
    }
  ],
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "InProgress",
  "startDateTime": "2026-09-14T08:12:40.513Z"
}

Note three keys from the response: the checklist's key, the first task's key and the key of its Invoice Number field. If your template has parameters, pass them in parameters — see Create a Checklist.

Open the url in a browser and you will see the new checklist in CheckFlow.

Step 5: Answer a Field​

The Check the invoice details task has a required Short Text field, so it cannot be completed until the field has a value. Set it:

curl -X PUT https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/tasks/1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62/fields/a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73 \
  -H "X-API-KEY: $CHECKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "INV-2041" }'

The answer is the field with its new value. Every control type has its own value format — a date, a list of options, a list of members — and Task Fields and Files describes each one. To set several fields in one request, use PUT .../fields with a fields array.

Step 6: Complete the Task​

curl -X POST https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/tasks/1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62/complete \
  -H "X-API-KEY: $CHECKFLOW_API_KEY"

The answer is the task as it now stands, with "status": "Complete", completedDateTime and completedBy — you. The checklist's activity feed records the completion in your name, exactly as if you had ticked the box in the app.

If the task cannot be completed — a required field is empty, or an earlier task halts it — the answer is 409 CONFLICT and the message says which. See Complete a Task.

What Next​

ToRead
Find checklists by status, template or the values in their fieldsChecklists
Assign tasks, set due dates and commentChecklist Tasks
React to events as they happen instead of pollingWebhooks
Page through long listsPagination
Handle errors properlyErrors
Build templates in codeTemplates and Template Documents
Let an AI assistant do all of this for youMCP Server

When you finish experimenting, revoke the Getting started key on the Team page, and create a key for each real integration.

Last updated on