# Create a template

`POST /api/v1/templates`

Define a new kind of record: what a contact page shows, or everything the account keeps about one kind of thing.

The template starts empty and goes at the end of your list. It is created with a draft version numbered 1 holding a single page and nothing on it, so there is somewhere to build before anything is published. Until you publish, the template has no published version and cannot be applied to a record.

The slug is settled here and never rebuilt afterwards, so a link that already went out keeps working through any rename. It is made from the name.

A template describing an entity has to name the type it describes, and that type has to be one of yours. A template describing a contact names none.

## Body parameters

- `name` (string, required): What the template is called. Up to 255 characters. Markup and surrounding blank space are stripped.
- `applies_to` (string, required): Either contact or entity.
- `description` (string, optional): What the template is for. Up to 65535 characters. Absent, empty or null all mean it has none.
- `entity_type_id` (uuid, optional): The entity type this template describes. Required when applies_to is entity, refused as invalid when the type belongs to somebody else, and ignored when applies_to is contact.

## Returns

The template that was created, with its settled slug and no published version.

- `data` (object): The template.
- `data.type` (string): Always template. 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.slug` (string): How the template is addressed in the application itself, in lower case letters, numbers and dashes. It is settled when the template is created and never rebuilt, so a link that already went out keeps working through any rename. Use it to build a browser link; use the id for every call here.
- `data.attributes.name` (string): What the template is called. A template the product supplied answers with the name translated into your language rather than the one stored, so the same template reads differently to two people.
- `data.attributes.description` (string): What the template is for, or null when nobody said.
- `data.attributes.applies_to` (string): Either contact or entity. A template describing a contact applies to the people in every vault; one describing an entity applies only to records of the type named in entity_type_id.
- `data.attributes.entity_type_id` (string): The id of the entity type this template describes, or null when it describes contacts. Read that type through the entity types endpoints.
- `data.attributes.is_system` (boolean): Whether the product supplied the template rather than you. It says where the template came from and locks nothing: a supplied template is renamed, moved, stopped and deleted exactly like one you made. Duplicating it first is usually the better move, because a copy leaves the original for anything already using it.
- `data.attributes.is_active` (boolean): Whether the template may still be applied to a record. False stops it being offered and touches nothing already using it: every record on it stays readable and stays editable.
- `data.attributes.position` (integer): Where the template sits in the list on the templates screen, counting from 1. It is the order you arranged, and it is the order the list endpoint answers in.
- `data.attributes.published_version_number` (integer): The number of the version records are put on when the template is applied today, or null when nothing has been published yet. A template with no published version is one still being designed.
- `data.attributes.created_at` (timestamp): When the template was created, as a count of seconds since 1970 rather than a written date.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds. Equal to created_at until it first changes.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.

## 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/templates \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Wine bottle",
      "applies_to": "contact",
      "description": "Everything the cellar holds."
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/templates', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Wine bottle',
    applies_to: 'contact',
    description: 'Everything the cellar holds.',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/templates', [
    'name' => 'Wine bottle',
    'applies_to' => 'contact',
    'description' => 'Everything the cellar holds.',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "template",
        "id": "7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af",
        "attributes": {
            "slug": "contact",
            "name": "Contact",
            "description": "What every person in a vault shows.",
            "applies_to": "contact",
            "entity_type_id": null,
            "is_system": false,
            "is_active": true,
            "position": 1,
            "published_version_number": 3,
            "created_at": 1756252800,
            "updated_at": 1756339200
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af"
        }
    }
}
```
