Skip to main content
Version: v2alpha1

Labels using the API

Steps​

1. Create new label​

Create a new label to be used in your resources by calling POST /labels. The response of the label creation contains the id of the label created that must be used in the resource creation to add the ne label to it.

Request​

POST /lables
{
  "name": "New Label",
  "color": "#FF0000",
  "description": "This is a new label"
}

Response​

201 Created
{
  "id": "lbl_1234567890abcdef",
  "text": "#FFFFFF"
}

2. Create resource adding labels​

You can create resources with labels by calling the resource creation endpoint and adding the label IDs to the labels field.

In this scenario, the resource created is an account with the label lbl_44678r08jtm8zbt227tzhc4nw5.

Request​

POST /accounts
{
  "reference": "New Account",
  "labels": ["lbl_44678r08jtm8zbt227tzhc4nw5"],
  [...]
}

Response​

201 Created
{
  "id": "acc_44678r08jtm8zbt227tzhc4nw5",
  "version": "20240213150344583",
  [...]
}

3. Update resource labels​

You can update the labels of a resource by calling the resource update endpoint and adding the label IDs to the labels. It will replace the existing labels with the new ones. In this scenario the resouce updated is the account acc_44678r08jtm8zbt227tzhc4nw5 with the label lbl_44678r08jtm8zbt227tzhc4nw5.

Request​

PATCH /accounts/acc_44678r08jtm8zbt227tzhc4nw5
{
  "labels": ["lbl_44678r08jtm8zbt227tzhc4nw5", "lbl_31672r10jtm6zvt127vzmc3sn2"],
  [...]
}

Response​

200 Ok
{
  "id": "acc_44678r08jtm8zbt227tzhc4nw5",
  "version": "20240213150344583",
  [...]
}