# Add a possession type

`POST /api/v1/possession-types`

Add a kind of thing your account owns. Add its groups and fields afterwards.

The change is written to the account log.

## Body parameters

- `name` (string, required): What the kind of thing is called. Up to 255 characters. Markup and surrounding blank space are stripped, and a name left with nothing in it is refused.
- `colour` (string, optional): One of the vault colours: #3f5fd0, #4f8a49, #9a6a24, #9a3f2b, #6b4fa8, #2f7f86, #a8447a or #4a4a52. Blue when left out.
- `icon` (string, optional): One of the glyphs of the catalogue. Anything else answers 422. None when left out.

## Returns

The possession type object that was added, with no group and no field yet.

- `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.
- `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, which is 0 for a new one.
- `data.attributes.groups` (array): The groups of fields, an empty list for a new type.
- `data.attributes.fields` (array): The standalone fields, an empty list for a new type.
- `data.attributes.created_at` (timestamp): When the type was added, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds.
- `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 \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Office equipment",
      "colour": "#2f7f86",
      "icon": "briefcase"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/possession-types', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Office equipment',
    colour: '#2f7f86',
    icon: 'briefcase',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/possession-types', [
    'name' => 'Office equipment',
    'colour' => '#2f7f86',
    'icon' => 'briefcase',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_type",
        "id": "9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35",
        "attributes": {
            "name": "Office equipment",
            "colour": "#2f7f86",
            "icon": "briefcase",
            "field_count": 0,
            "groups": [],
            "fields": [],
            "created_at": 1761436800,
            "updated_at": 1761436800
        },
        "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"
        }
    }
}
```
