# Add a group of fields

`POST /api/v1/possession-types/{possessionType}/groups`

Add a named group of fields to a possession type, placed after the other groups.

## Parameters

- `possessionType` (uuid, required): The id of the possession type. A type belonging to somebody else answers 404.
- `name` (string, required): What the group is called. Up to 255 characters. Markup and surrounding blank space are stripped, and a name left with nothing in it is refused.

## Returns

The possession type object, with the new group.

- `data` (object): The possession type.
- `data.type` (string): Always possession_type. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.name` (string): What the kind of thing is called: office equipment, a vehicle, a musical instrument.
- `data.attributes.colour` (string): One of the eight vault colours, as a hexadecimal value.
- `data.attributes.icon` (string): One of the glyphs of the catalogue (the same list sections and possession conditions use), or null. A type without one is drawn with a blank page.
- `data.attributes.field_count` (integer): How many fields the type has, grouped or not.
- `data.attributes.groups` (array): The groups of fields, in order.
- `data.attributes.groups[]` (object): One group.
- `data.attributes.groups[].id` (uuid): The id of the group.
- `data.attributes.groups[].name` (string): What the group is called, such as Purchase.
- `data.attributes.groups[].position` (integer): Its place among the groups, counting from 1.
- `data.attributes.groups[].fields` (array): The fields of the group, in order.
- `data.attributes.groups[].fields[]` (object): One field.
- `data.attributes.groups[].fields[].id` (uuid): The id of the field.
- `data.attributes.groups[].fields[].name` (string): What the field is called, such as Serial number.
- `data.attributes.groups[].fields[].kind` (string): What the field holds: text, number, date, boolean, select, or rating from one to five.
- `data.attributes.groups[].fields[].options` (array): The choices of a select field, in order, or null for every other kind.
- `data.attributes.groups[].fields[].options[]` (string): One choice.
- `data.attributes.groups[].fields[].position` (integer): Its place among its siblings, counting from 1.
- `data.attributes.groups[].fields[].group_id` (uuid): The group it sits in, or null when it stands alone.
- `data.attributes.fields` (array): The fields standing outside any group, in order.
- `data.attributes.fields[]` (object): One field.
- `data.attributes.fields[].id` (uuid): The id of the field.
- `data.attributes.fields[].name` (string): What the field is called, such as Serial number.
- `data.attributes.fields[].kind` (string): What the field holds: text, number, date, boolean, select, or rating from one to five.
- `data.attributes.fields[].options` (array): The choices of a select field, in order, or null for every other kind.
- `data.attributes.fields[].options[]` (string): One choice.
- `data.attributes.fields[].position` (integer): Its place among its siblings, counting from 1.
- `data.attributes.fields[].group_id` (uuid): The group it sits in, or null when it stands alone.
- `data.attributes.created_at` (timestamp): When the type was added, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When its name, colour or icon last changed, as a count of seconds, or null.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The screen where the possession type is edited in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/possession-types/9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35/groups \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Purchase"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/possession-types/9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35/groups', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Purchase',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/possession-types/9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35/groups', [
    'name' => 'Purchase',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_type",
        "id": "9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35",
        "attributes": {
            "name": "Office equipment",
            "colour": "#2f7f86",
            "icon": "briefcase",
            "field_count": 3,
            "groups": [
                {
                    "id": "4f2a8c61-7d93-4e05-b1c8-93a6d5e20b17",
                    "name": "Purchase",
                    "position": 1,
                    "fields": [
                        {
                            "id": "b7e04a93-1c6f-4d28-9a35-6f8e2d1c4b90",
                            "name": "Payment method",
                            "kind": "select",
                            "options": [
                                "Cash",
                                "Card"
                            ],
                            "position": 1,
                            "group_id": "4f2a8c61-7d93-4e05-b1c8-93a6d5e20b17"
                        }
                    ]
                }
            ],
            "fields": [
                {
                    "id": "e5c37a28-9f14-4b6d-a083-7d2e1f9b6c45",
                    "name": "Condition",
                    "kind": "select",
                    "options": [
                        "New",
                        "Used",
                        "Broken"
                    ],
                    "position": 1,
                    "group_id": null
                },
                {
                    "id": "2d8b5f1e-6a47-4c93-8e02-1b9f7c3a5d64",
                    "name": "Serial number",
                    "kind": "text",
                    "options": null,
                    "position": 2,
                    "group_id": null
                }
            ],
            "created_at": 1761436800,
            "updated_at": 1761440400
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/possession-types/9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35",
            "web": "https://my.monicahq.com/settings/account/possession-types/9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35/edit"
        }
    }
}
```
