# Attributes

Manage and get attributes

**Field Types**

| **type** | **description** |
| --- | --- |
| `1` | Single Select |
| `2` | Multi Select |
| `3` | Open Value (Single) |
| `4` | Open Value (Multiple) |
| `5` | Attachments |
| `6` | Textarea |
| `7` | Date/time |
| `8` | Number |
| `9` | Boolean |
| `10` | Color |
| `11` | JSON |
| `12` | Location |
| `13` | Audio file |
| `14` | Video file |

### Field type value format

| **field type** | **value format** |
| --- | --- |
| Single Select (`1`) | One attribute value ID or value. |
| Multi Select (`2`) | An array of attribute value IDs or values. |
| Open Value (`3`) | One free-form string or scalar value. |
| Open Value Multiple (`4`) | An array of free-form values. |
| Attachments (`5`) | An array of uploaded file URLs or file references. |
| Textarea (`6`) | A free-form string, typically multiline text. |
| Date/time (`7`) | An ISO-8601 date/time string. |
| Number (`8`) | A numeric value. |
| Boolean (`9`) | `true` or `false`. |
| Color (`10`) | A color string such as a hex value (`#FF0000`). |
| JSON (`11`) | A valid JSON object or array. |
| Location (`12`) | A location object, normally containing latitude and longitude. |
| Audio file (`13`) | An uploaded audio URL or file reference. |
| Video file (`14`) | An uploaded video URL or file reference. |

## Attribute response object

An attribute describes one custom field for an object type (for example, a
listing or account). `field_type` is the input/value format; `type` is the
object scope and must not be confused with `field_type`.

**Sample Object**

```
{
    "id": 71,
    "type": "listings",
    "field_type": 4,
    "icon_path": null,
    "optional": true,
    "private": false,
    "show_in_filter": true,
    "visible": true,
    "active": true,
    "order_by": 1,
    "attribute_group_id": 12,
    "metadata": {},
    "name": "Fabric",
    "tooltip": "Select all applicable fabrics",
    "categories": [
        {
            "id": 252,
            "parent": 9,
            "type": "listings",
            "active": true,
            "image_path": "https://cdn2.iconfinder.com/data/icons/shirts-glyph/48/Clothing_Shirts_Artboard_2-512.png",
            "order_by": 1,
            "sub_category": [],
            "name": "V-Neck",
            "hierarchy": [
                {
                    "id": 252,
                    "name": "V-Neck",
                    "level": 3
                }
            ]
        }
    ]
}

```

**Attribute Object fields**

| **name** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | unique id of the attribute |
| `name` | `string` | name of the attribute |
| `field_type` | `integer` | field type of the attribute. refer to field type legend here |
| `icon_path` | `string \| null` | optional icon/image associated with the attribute |
| `optional` | `boolean` | states whether this attribute is optional or not |
| `private` | `boolean` | states whether this attribute is private or not. private attributes are visible only to admins |
| `show_in_filter` | `boolean` | states whether this attribute is shown in filter list or not |
| `visible` | `boolean` | controls whether the attribute is shown to clients |
| `active` | `boolean` | states whether this attribute is active or not |
| `order_by` | `integer` | display order among attributes |
| `type` | `string` | type of the object being returned |
| `attribute_group_id` | `integer \| null` | optional group used to organise related attributes |
| `metadata` | `object \| array \| null` | additional tenant-defined configuration; preserve its JSON shape |
| `tooltip` | `string \| null` | optional help text displayed for the field |
| `categories` | `array` | categories mapped to this attribute. refer to category object here |
| `values` | `array` | active options for field types 1 and 2; each option includes its `id`, `name`, `active`, `order_by`, and `metadata` |

`values` is returned for select attributes only. Use an option's `id` when
submitting a select value; do not invent option IDs.

## Submitting and storing values

Product/account attribute input uses an array of objects. Each object contains
the attribute ID and an array named `values`, even when the field accepts only
one value:

```json
{
  "attributes": [
    { "id": 71, "values": ["cotton", "linen"] },
    { "id": 72, "values": [true] }
  ]
}
```

Single-value fields must contain exactly one item in `values`. Select and
multi-select fields use IDs from the attribute's `values` list. File fields
must be uploaded first and then receive the resulting URL/reference. The API
persists the submitted values as JSON, so clients should retain the documented
JSON type rather than sending a stringified boolean, number, or object.

## Type-specific rules

| **field type** | **expected value** | **important rule** |
| --- | --- | --- |
| Single Select (`1`) | one option ID | option must be active and belong to this attribute |
| Multi Select (`2`) | array of option IDs | every option must be active and belong to this attribute |
| Open Value (`3`) | one scalar/free-form value | exactly one item |
| Open Value Multiple (`4`) | array of free-form values | multiple items allowed |
| Attachments (`5`) | array of file URLs/references | upload files before submission |
| Textarea (`6`) | one string | multiline text is allowed |
| Date/time (`7`) | one date/time string | use a parseable ISO-8601 value, preferably UTC (`2026-09-15T10:30:00Z`) |
| Number (`8`) | one number | send a JSON number, not a formatted string |
| Boolean (`9`) | one boolean | send `true`/`false`, not `"true"`/`"false"` |
| Color (`10`) | one color string | hex (`#RGB`/`#RRGGBB`) or `rgb(a)`/`hsl(a)` format |
| JSON (`11`) | one JSON object or array | must be valid JSON and remain structured |
| Location (`12`) | one object | include numeric `latitude` (-90..90) and `longitude` (-180..180) |
| Audio file (`13`) | uploaded audio URL/reference | upload first; keep the returned reference |
| Video file (`14`) | uploaded video URL/reference | upload first; keep the returned reference |