> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scoutworks.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Grants and funding tracker

> Keep a board of grant applications in Scoutworks up to date from a script or a bot: add each new grant as a task, then move it along as it progresses.

Many groups keep a list of grants to apply for, with deadlines, somewhere outside Scoutworks. This recipe keeps that list on a Scoutworks **task board** instead, where the rest of the team can see it. A script or bot adds each grant as a task and moves it between columns as the application progresses.

It takes about ten minutes.

## 1. Make the board

In Scoutworks, open **Tasks** and create a board called **Grants**. Give it columns for each stage, for example **To apply**, **Applied** and **Awarded**. Make **Awarded** the done column: a task in the done column counts as complete. Add labels if they help, for example **Capital** and **Activities**.

## 2. Create a key

A group admin creates a key in **Settings → Integrations → API keys** with the scopes **`tasks:read`** and **`tasks:write`**. Tasks the key adds show that admin as their creator. See [Authentication](https://developers.scoutworks.app/guides/authentication.md).

## 3. Find the board's ids

The script needs the board's id, and the ids of its columns and labels. One request lists them:

```bash theme={null}
curl https://api.scoutworks.app/api/v1/task-boards \
  -H "Authorization: Bearer $SCOUTWORKS_API_KEY"
```

Each board has `columns` left to right, with `done: true` on the done column, and `labels`.

## 4. Add a grant

Add a task with a title, a due date and, if you like, a priority, notes and labels. Leave out `columnId` and the task goes into the board's first column.

```bash theme={null}
curl -X POST https://api.scoutworks.app/api/v1/tasks \
  -H "Authorization: Bearer $SCOUTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: grant-community-fund-2027" \
  -d '{
    "boardId": "PASTE_BOARD_ID",
    "title": "Community fund: new tents",
    "dueDate": "2027-01-31T17:00:00Z",
    "priority": "high",
    "description": "£2,500 for six patrol tents. Apply online."
  }'
```

> [!TIP]
>
> Send an `Idempotency-Key` that is unique to the grant, for example its name and year. If the request times out and your script sends it again, Scoutworks answers with the task it already added instead of adding a second one.

## 5. Move it along

When you apply, move the task to the next column. When the money arrives, move it to the done column and it is marked complete.

```bash theme={null}
curl -X PATCH https://api.scoutworks.app/api/v1/tasks/PASTE_TASK_ID \
  -H "Authorization: Bearer $SCOUTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "columnId": "PASTE_COLUMN_ID" }'
```

Send only the fields you want to change. `labelIds` replaces the task's labels, and `"dueDate": null` clears the due date.

## 6. Read it back

List the board's tasks to see where every grant stands:

```bash theme={null}
curl "https://api.scoutworks.app/api/v1/tasks?boardId=PASTE_BOARD_ID" \
  -H "Authorization: Bearer $SCOUTWORKS_API_KEY"
```

A bot that checks often can pass `updatedSince` to read only what changed. See [Pagination](https://developers.scoutworks.app/guides/pagination.md).

The API never returns a task's description, because it is free text. You can read it in Scoutworks.

## If something goes wrong

* **`402 subscription_required`**: the group's subscription has lapsed. The key can still read, but not change anything.
* **`404 not_found`** for a board: no board with that id in your group, or it was deleted. A key reaches every board in the group, restricted ones included.
* **`400 invalid_request`** on the trustee duties board: a trustee duty needs a `dueDate`.
* **`400 invalid_request`** for a label: the label is not on the task's board.

See [Errors](https://developers.scoutworks.app/guides/errors.md) for every code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.