# Plaky integration overview

> Create Plaky board items and update their field values from Persona Workflows, and look up the spaces, boards, groups, and items they belong to.

Source: https://help.withpersona.com/articles/PQH4Jk0RtGJQGZDIKXE3Fv/
Section: Marketplace and 3rd-Party Integrations > Productivity > Plaky

## Overview

[Plaky](https://plaky.com/) is a project and task management platform from CAKE.com. Teams organize work in spaces and boards, and each board holds items arranged in item groups, with customizable fields such as status, tags, people, dates, numbers, links, and timelines.

Persona's Plaky integration lets a Workflow create items on a Plaky board and change an item's field values. For example, a Workflow can open an item for every Inquiry that needs manual review, assign it to a reviewer, and move its status to **Done** once the review is resolved.

## Integration features

The Plaky integration supports these Workflow actions:

- **Get spaces:** List the spaces in the Plaky workspace the API key belongs to.
- **Get boards for space:** List the boards in a space, including each board's fields and item groups.
- **Get board by ID:** Retrieve one board with its field definitions, item groups, and default values.
- **Get item groups for board:** List the item groups on a board.
- **Get items with filters:** List the items on a board, optionally filtered by a saved board view or a parent item.
- **Create item:** Create an item or subitem on a board, with initial field values.
- **Change item field value:** Set the value of a single field on an existing item.

## Prerequisites

Before configuring the integration, you need:

- A Plaky account with the Owner, Admin, or Member role. API keys are available on every Plaky pricing plan.
- A Plaky API key.
- At least one board in the space you want to work in. The API cannot create boards, so create the board in the Plaky app first.

## Set up Plaky credentials

1. In Plaky, click your profile picture in the top-right corner and select **Preferences**.
2. Open the **Advanced** tab and click **Manage API keys**.
3. Click **Generate API key**, enter a name for the key, and click **Generate**. Copy the key; it carries the same workspace, role, and permissions as your Plaky user.
4. In the Persona Dashboard, go to **Integrations > Marketplace** and select **Plaky**.
5. Click **Add Credential**, enter a nickname for the credential, and paste the API key.
6. Save the credential.

## Use Plaky in a Workflow

1. Create a Workflow, or open the Workflow you want to update.
2. Add an **Action** step and select **Integrations**.
3. Select **Plaky**, choose the saved credential, and select an action.
4. Map Persona data to the action's input fields.
5. Save and publish the Workflow.

## Plaky actions

Most actions need IDs from the actions before them, so a typical setup looks up the Space ID, then the Board ID, then the Field Keys and Group IDs on that board.

### Get spaces

Returns the spaces you can access, with each space's ID and title. Use it to find the **Space ID** the other actions require.

**Optional fields:** Expand, Page, Page Size.

### Get boards for space and Get board by ID

**Get boards for space** returns the boards in a space with their fields and groups. **Get board by ID** returns a single board. Use either to find:

- the **Board ID**
- each field's **Field Key**, such as `status-1` or `person-1`
- the labels a status or tag field accepts, such as `To do`, `In progress`, and `Done`

**Required fields:** Space ID, plus Board ID for Get board by ID.

### Get item groups for board

Returns the item groups on a board, with each group's ID, title, and color. Use it to find the **Group ID** for a new item.

**Required fields:** Space ID, Board ID.

### Get items with filters

Returns the items on a board. Use it to find the **Item ID** for Change item field value.

**Required fields:** Space ID, Board ID.

**Optional fields include:**

- **Board View ID:** Apply the filters and sorting saved on a board view. Plaky has no way to list board views through the API, so open the view in the Plaky app and copy the numeric view ID from the browser URL.
- **Parent Item ID:** Return only the subitems of one item.
- **Subitems Behaviour:** Include subitems at the top level, exclude them, or embed them inside their parent.
- **Expand:** Return full objects, such as people and status labels, instead of bare IDs.
- **Page** and **Page Size**

### Create item

Creates an item on a board and returns it with every field's current value.

**Required fields:** Space ID, Board ID.

**Optional fields include:**

- **Title**
- **Group ID** or **Group Title:** When both are set, Group ID wins. When neither is set, the item goes into the first group on the board.
- **Parent Item ID:** Create a subitem of an existing item instead of a top-level item.
- **Fields:** Initial field values, keyed by field key (`status-1`) or field title (`Status`). Leave this empty to use the board's default values.
- **Subscribed User IDs** and **Subscribed Team IDs**

### Change item field value

Sets the value of one field on an item and returns the updated item.

**Required fields:** Space ID, Board ID, Item ID, Field Key, Value.

The field must be identified by its key, not its title. The shape of **Value** depends on the field type:

| Field type       | Value                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------- |
| Text / Rich text | `"some text"`                                                                                 |
| Number           | `13.4`                                                                                        |
| Date             | `"2017-06-02T18:10:15.254Z"`                                                                  |
| Timeline         | `{"start": "2026-01-02T18:10:15.254Z", "end": "2026-02-02T18:10:15.254Z"}`                    |
| Status           | `"Done"` (label title) or `"1"` (label key)                                                   |
| Tag              | `["Product", "HR"]` (label titles) or `["1", "2"]` (label keys)                               |
| Link             | `"https://www.example.com"` or `{"url": "https://www.example.com", "displayText": "Example"}` |
| Person           | `{"users": [{"id": 1}, {"email": "user@example.com"}], "teams": [{"title": "Backend Team"}]}` |

Person fields accept a user's email address or a team's title, so you can assign people without looking up their IDs.

## FAQs

### Why does Change item field value return an error?

A value that matches none of the field's labels returns `ILLEGAL_ATTRIBUTE_VALUE`, and a field key that does not exist on the board returns `ITEM_ATTRIBUTE_NOT_FOUND`. Use Get board by ID to confirm the field key and the labels it accepts.

### Does Plaky limit API requests?

Yes. Plaky allows 200 requests per user per minute and returns HTTP `429` above that.

## Plans Explained

### Plaky Integration by plan

|                   | Startup Program | Essential Plan | Growth Plan | Enterprise Plan |
| ----------------- | --------------- | -------------- | ----------- | --------------- |
| Plaky Integration | Not Available   | Not Available  | Limited     | Available       |

[Learn more about pricing and plans](https://withpersona.com/pricing?utm_source=product&utm_medium=referral&utm_audience=a&utm_campaign=cm_gen_ds_hc-plan-table).