Category field
- cURL
- JSON
curl -X POST https://api.tapeapp.com/v1/app/ \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"workspace_id": 1,
"name": "Leads",
"item_name": "Lead",
"fields": [
{
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"description": "The current stage of the lead in the sales pipeline.",
"required": true,
"settings": {
"options": [
{ "text": "New", "color": "gray" },
{ "text": "Contacted", "color": "blue" },
{ "text": "Won", "color": "green" },
{ "text": "Lost", "color": "red" }
]
}
}
},
{
"field_type": "multi_category",
"config": {
"label": "Products",
"description": "The products the lead is interested in.",
"settings": {
"layout": "list",
"options": [
{ "text": "Solar panels", "color": "yellow" },
{ "text": "Battery storage", "color": "green" },
{ "text": "Heat pump" }
]
}
}
}
]
}'
{
"workspace_id": 1,
"name": "Leads",
"item_name": "Lead",
"fields": [
{
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"description": "The current stage of the lead in the sales pipeline.",
"required": true,
"settings": {
"options": [
{ "text": "New", "color": "gray" },
{ "text": "Contacted", "color": "blue" },
{ "text": "Won", "color": "green" },
{ "text": "Lost", "color": "red" }
]
}
}
},
{
"field_type": "multi_category",
"config": {
"label": "Products",
"description": "The products the lead is interested in.",
"settings": {
"layout": "list",
"options": [
{ "text": "Solar panels", "color": "yellow" },
{ "text": "Battery storage", "color": "green" },
{ "text": "Heat pump" }
]
}
}
}
]
}
{
"app_id": 1,
"workspace_id": 1,
"slug": "leads",
"external_id": "leads",
"name": "Leads",
"record_name": "Lead",
"item_name": "Lead",
"type": "database",
"config": {
"item_name": "Lead",
"name": "Leads"
},
"fields": [
{
"field_id": 1,
"external_id": "pipeline_stage",
"slug": "pipeline_stage",
"label": "Pipeline Stage",
"type": "category",
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"slug": "pipeline_stage",
"external_id": "pipeline_stage",
"description": "The current stage of the lead in the sales pipeline.",
"show_description": false,
"required": true,
"always_hidden": false,
"hidden_if_empty": false,
"primary": true,
"settings": {
"multiple": false,
"layout": "dropdown",
"options": [
{ "id": 1, "text": "New", "color": "6E7174" },
{ "id": 2, "text": "Contacted", "color": "0077DE" },
{ "id": 3, "text": "Won", "color": "00866A" },
{ "id": 4, "text": "Lost", "color": "FE001A" }
]
}
}
},
{
"field_id": 2,
"external_id": "products",
"slug": "products",
"label": "Products",
"type": "category",
"field_type": "multi_category",
"config": {
"label": "Products",
"slug": "products",
"external_id": "products",
"description": "The products the lead is interested in.",
"show_description": false,
"required": false,
"always_hidden": false,
"hidden_if_empty": false,
"primary": false,
"settings": {
"multiple": true,
"layout": "list",
"options": [
{ "id": 5, "text": "Solar panels", "color": "DEA700" },
{ "id": 6, "text": "Battery storage", "color": "00866A" },
{ "id": 7, "text": "Heat pump", "color": "6E7174" }
]
}
}
}
]
}
- cURL
- JSON
curl -X PUT https://api.tapeapp.com/v1/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": [
{
"field_id": 1,
"config": {
"label": "Pipeline Stage",
"required": true,
"settings": {
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "gray" },
{ "id": 2, "text": "Contacted", "color": "blue" },
{ "text": "Negotiating", "color": "yellow" },
{ "id": 3, "text": "Won", "color": "green" },
{ "id": 4, "text": "Lost", "color": "orange" }
]
}
}
}
]
}'
{
"fields": [
{
"field_id": 1,
"config": {
"label": "Pipeline Stage",
"required": true,
"settings": {
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "gray" },
{ "id": 2, "text": "Contacted", "color": "blue" },
{ "text": "Negotiating", "color": "yellow" },
{ "id": 3, "text": "Won", "color": "green" },
{ "id": 4, "text": "Lost", "color": "orange" }
]
}
}
}
]
}
{
"app_id": 1,
"workspace_id": 1,
"slug": "leads",
"external_id": "leads",
"name": "Leads",
"record_name": "Lead",
"item_name": "Lead",
"type": "database",
"config": {
"item_name": "Lead",
"name": "Leads"
},
"fields": [
{
"field_id": 1,
"external_id": "pipeline_stage",
"slug": "pipeline_stage",
"label": "Pipeline Stage",
"type": "category",
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"slug": "pipeline_stage",
"external_id": "pipeline_stage",
"description": "The current stage of the lead in the sales pipeline.",
"show_description": false,
"required": true,
"always_hidden": false,
"hidden_if_empty": false,
"primary": true,
"settings": {
"multiple": false,
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "6E7174" },
{ "id": 2, "text": "Contacted", "color": "0077DE" },
{ "id": 8, "text": "Negotiating", "color": "DEA700" },
{ "id": 3, "text": "Won", "color": "00866A" },
{ "id": 4, "text": "Lost", "color": "F45D00" }
]
}
}
},
{
"field_id": 2,
"external_id": "products",
"slug": "products",
"label": "Products",
"type": "category",
"field_type": "multi_category",
"config": {
"label": "Products",
"slug": "products",
"external_id": "products",
"description": "The products the lead is interested in.",
"show_description": false,
"required": false,
"always_hidden": false,
"hidden_if_empty": false,
"primary": false,
"settings": {
"multiple": true,
"layout": "list",
"options": [
{ "id": 5, "text": "Solar panels", "color": "DEA700" },
{ "id": 6, "text": "Battery storage", "color": "00866A" },
{ "id": 7, "text": "Heat pump", "color": "6E7174" }
]
}
}
}
]
}
Use a category field to let a record pick from a fixed list of options, like a pipeline stage or a product.
Tape has two category field types:
single_categoryis the Single select field. A record holds at most one option.multi_categoryis the Multiple select field. A record holds any number of options.
A category field has the common field properties and settings with its options and layout. To read and set the selected options of a record, see Category field value.
{
"field_id": 1,
"external_id": "pipeline_stage",
"slug": "pipeline_stage",
"label": "Pipeline Stage",
"type": "category",
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"slug": "pipeline_stage",
"external_id": "pipeline_stage",
"description": "The current stage of the lead in the sales pipeline.",
"show_description": true,
"required": true,
"always_hidden": false,
"hidden_if_empty": false,
"primary": true,
"settings": {
"multiple": false,
"layout": "dropdown",
"options": [
{ "id": 1, "text": "New", "color": "6E7174" },
{ "id": 2, "text": "Contacted", "color": "0077DE" },
{ "id": 3, "text": "Won", "color": "00866A" },
{ "id": 4, "text": "Lost", "color": "FE001A" }
]
}
}
}
typestring
"category" for both category field types.
field_typestring
"single_category" or "multi_category".
config.settings.multiple (read-only)boolean
false for single_category, true for multi_category.
config.settings.layoutstring
Older layout setting: "dropdown" (default), "list" or "inline". Tape stores and returns the value, but it doesn't change how the options look. Set that in the record layout of the app.
config.settings.optionsarray
The options of the field, in their order.
config.settings.options[].idnumber
ID of the option. Use it to change the option or to select it in a record.
config.settings.options[].textstring
Label of the option. Required for every option you send.
config.settings.options[].colorstring
Color of the option. Responses return a hex value without #. See Option colors.
config.settings.options_to_delete (write-only)array
App update only. The IDs of the options to delete.
| Property | Type | Description | Example value |
|---|---|---|---|
type | string | "category" for both category field types. | "category" |
field_type | string | "single_category" or "multi_category". | "single_category" |
config.settings.multiple (read-only) | boolean | false for single_category, true for multi_category. | false |
config.settings.layout | string | Older layout setting: "dropdown" (default), "list" or "inline". Tape stores and returns the value, but it doesn't change how the options look. Set that in the record layout of the app. | "dropdown" |
config.settings.options | array | The options of the field, in their order. | |
config.settings.options[].id | number | ID of the option. Use it to change the option or to select it in a record. | 2 |
config.settings.options[].text | string | Label of the option. Required for every option you send. | "Contacted" |
config.settings.options[].color | string | Color of the option. Responses return a hex value without #. See Option colors. | "0077DE" |
config.settings.options_to_delete (write-only) | array | App update only. The IDs of the options to delete. | [{ "id": 4 }] |
Option colors
Send a color by name or as its hex value without #. Tape reads names case-insensitively.
An unknown color gives the option the default color (CDCCC9), without an error. This includes a hex value with #.
default
CDCCC9
gray
6E7174
brown
8B2E00
orange
F45D00
yellow
DEA700
green
00866A
blue
0077DE
purple
6724DD
pink
DC0080
red
FE001A
| Name | Hex value |
|---|---|
default | CDCCC9 |
gray | 6E7174 |
brown | 8B2E00 |
orange | F45D00 |
yellow | DEA700 |
green | 00866A |
blue | 0077DE |
purple | 6724DD |
pink | DC0080 |
red | FE001A |
App creation
Use the create app endpoint to create category fields together with a new app.
/v1/appapi.tapeapp.com- cURL
- JSON
curl -X POST https://api.tapeapp.com/v1/app/ \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"workspace_id": 1,
"name": "Leads",
"item_name": "Lead",
"fields": [
{
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"description": "The current stage of the lead in the sales pipeline.",
"required": true,
"settings": {
"options": [
{ "text": "New", "color": "gray" },
{ "text": "Contacted", "color": "blue" },
{ "text": "Won", "color": "green" },
{ "text": "Lost", "color": "red" }
]
}
}
},
{
"field_type": "multi_category",
"config": {
"label": "Products",
"description": "The products the lead is interested in.",
"settings": {
"layout": "list",
"options": [
{ "text": "Solar panels", "color": "yellow" },
{ "text": "Battery storage", "color": "green" },
{ "text": "Heat pump" }
]
}
}
}
]
}'
{
"workspace_id": 1,
"name": "Leads",
"item_name": "Lead",
"fields": [
{
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"description": "The current stage of the lead in the sales pipeline.",
"required": true,
"settings": {
"options": [
{ "text": "New", "color": "gray" },
{ "text": "Contacted", "color": "blue" },
{ "text": "Won", "color": "green" },
{ "text": "Lost", "color": "red" }
]
}
}
},
{
"field_type": "multi_category",
"config": {
"label": "Products",
"description": "The products the lead is interested in.",
"settings": {
"layout": "list",
"options": [
{ "text": "Solar panels", "color": "yellow" },
{ "text": "Battery storage", "color": "green" },
{ "text": "Heat pump" }
]
}
}
}
]
}
{
"app_id": 1,
"workspace_id": 1,
"slug": "leads",
"external_id": "leads",
"name": "Leads",
"record_name": "Lead",
"item_name": "Lead",
"type": "database",
"config": {
"item_name": "Lead",
"name": "Leads"
},
"fields": [
{
"field_id": 1,
"external_id": "pipeline_stage",
"slug": "pipeline_stage",
"label": "Pipeline Stage",
"type": "category",
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"slug": "pipeline_stage",
"external_id": "pipeline_stage",
"description": "The current stage of the lead in the sales pipeline.",
"show_description": false,
"required": true,
"always_hidden": false,
"hidden_if_empty": false,
"primary": true,
"settings": {
"multiple": false,
"layout": "dropdown",
"options": [
{ "id": 1, "text": "New", "color": "6E7174" },
{ "id": 2, "text": "Contacted", "color": "0077DE" },
{ "id": 3, "text": "Won", "color": "00866A" },
{ "id": 4, "text": "Lost", "color": "FE001A" }
]
}
}
},
{
"field_id": 2,
"external_id": "products",
"slug": "products",
"label": "Products",
"type": "category",
"field_type": "multi_category",
"config": {
"label": "Products",
"slug": "products",
"external_id": "products",
"description": "The products the lead is interested in.",
"show_description": false,
"required": false,
"always_hidden": false,
"hidden_if_empty": false,
"primary": false,
"settings": {
"multiple": true,
"layout": "list",
"options": [
{ "id": 5, "text": "Solar panels", "color": "DEA700" },
{ "id": 6, "text": "Battery storage", "color": "00866A" },
{ "id": 7, "text": "Heat pump", "color": "6E7174" }
]
}
}
}
]
}
The example creates a leads app for a solar installer in the workspace with ID 1. The app gets a single_category field "Pipeline Stage" and a multi_category field "Products". The example leaves out other fields of a leads app, like "Name" or "Company".
Find the workspace ID with Retrieve workspaces.
General behavior
- Tape keeps the order of
optionsfrom the request. - Without
layout, a new field uses"dropdown". - Without
color, a new option is gray (6E7174). Here, that's "Heat pump". - Without
primary, Tape makes the first field of the request the primary field. Here, that's "Pipeline Stage". - A new category field doesn't show its
descriptionas help text (show_descriptionisfalse).
Requirements: apps:edit, and a workspace role that may edit apps in the workspace. Works with a personal access token, an OAuth access token or a user API key.
Errors
- An option without
textreturns400. - A
layoutother than"dropdown","list"or"inline"returns400.
App update
Use the update app endpoint to create new category fields in an app or to change existing ones.
/v1/app/{appId}api.tapeapp.com- cURL
- JSON
curl -X PUT https://api.tapeapp.com/v1/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": [
{
"field_id": 1,
"config": {
"label": "Pipeline Stage",
"required": true,
"settings": {
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "gray" },
{ "id": 2, "text": "Contacted", "color": "blue" },
{ "text": "Negotiating", "color": "yellow" },
{ "id": 3, "text": "Won", "color": "green" },
{ "id": 4, "text": "Lost", "color": "orange" }
]
}
}
}
]
}'
{
"fields": [
{
"field_id": 1,
"config": {
"label": "Pipeline Stage",
"required": true,
"settings": {
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "gray" },
{ "id": 2, "text": "Contacted", "color": "blue" },
{ "text": "Negotiating", "color": "yellow" },
{ "id": 3, "text": "Won", "color": "green" },
{ "id": 4, "text": "Lost", "color": "orange" }
]
}
}
}
]
}
{
"app_id": 1,
"workspace_id": 1,
"slug": "leads",
"external_id": "leads",
"name": "Leads",
"record_name": "Lead",
"item_name": "Lead",
"type": "database",
"config": {
"item_name": "Lead",
"name": "Leads"
},
"fields": [
{
"field_id": 1,
"external_id": "pipeline_stage",
"slug": "pipeline_stage",
"label": "Pipeline Stage",
"type": "category",
"field_type": "single_category",
"config": {
"label": "Pipeline Stage",
"slug": "pipeline_stage",
"external_id": "pipeline_stage",
"description": "The current stage of the lead in the sales pipeline.",
"show_description": false,
"required": true,
"always_hidden": false,
"hidden_if_empty": false,
"primary": true,
"settings": {
"multiple": false,
"layout": "list",
"options": [
{ "id": 1, "text": "New", "color": "6E7174" },
{ "id": 2, "text": "Contacted", "color": "0077DE" },
{ "id": 8, "text": "Negotiating", "color": "DEA700" },
{ "id": 3, "text": "Won", "color": "00866A" },
{ "id": 4, "text": "Lost", "color": "F45D00" }
]
}
}
},
{
"field_id": 2,
"external_id": "products",
"slug": "products",
"label": "Products",
"type": "category",
"field_type": "multi_category",
"config": {
"label": "Products",
"slug": "products",
"external_id": "products",
"description": "The products the lead is interested in.",
"show_description": false,
"required": false,
"always_hidden": false,
"hidden_if_empty": false,
"primary": false,
"settings": {
"multiple": true,
"layout": "list",
"options": [
{ "id": 5, "text": "Solar panels", "color": "DEA700" },
{ "id": 6, "text": "Battery storage", "color": "00866A" },
{ "id": 7, "text": "Heat pump", "color": "6E7174" }
]
}
}
}
]
}
The example changes the "Pipeline Stage" field (ID 1) of the leads app. It adds the option "Negotiating" between "Contacted" and "Won", changes the color of "Lost" to orange and sets layout to "list". The "Products" field isn't in the request, so it stays unchanged.
Find the app ID and the field IDs in the Developer view of the app. Find the option IDs in config.settings.options of the field, for example with Retrieve a single app.
General behavior
- A field with
field_idupdates that field. A field withoutfield_idcreates a new field and needs afield_type. - An option with
idchanges that option. To rename it, send itsidwith the newtext. An option withoutidcreates a new option. - Options you leave out of
optionsstay unchanged. To set a new order, send all existing options in that order. - An option you send without the other options moves to the end of the list, also when you only rename it. To keep the order, send all options in the order you want.
- To delete options, list their IDs in
settings.options_to_delete, for example"options_to_delete": [{ "id": 4 }]. Tape also accepts plain IDs:[4]. An option that is also inoptionsstays. - Without
layout, the field keeps its layout. - Send
required,always_hiddenandhidden_if_emptywith every field you update. Tape sets left-out switches tofalse.show_descriptionstays as it is, with or withoutdescription. See Create and update fields. - Fields that aren't in the request stay unchanged.
Requirements: apps:edit, and Full access to the app. Works with a personal access token, an OAuth access token or a user API key.
Errors
- Every field you update needs
config.label, even if the label stays the same. Without it, Tape rejects the request with400andinput_validation. The message reads, for example,Invalid input: data/fields/0/config must have required property 'label'. - An option without
textreturns400. - An option ID in
optionsoroptions_to_deletethat doesn't belong to the field returns400. - A
layoutother than"dropdown","list"or"inline"returns400.