# Create custom field

> Creates a custom field on your team's people. The key is derived from the label. DROPDOWN fields need a non-empty options list. Creating the same label with…

`POST /v2/api/crm/attributes`

<Note>
**Required scope:** `CRM_WRITE`
</Note>

## Body fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | string | yes | Display name, 1 to 255 characters, with at least one letter or digit |
| `type` | string | yes | `TEXT`, `NUMBER`, `DATE`, `BOOLEAN` or `DROPDOWN` |
| `options` | array | `DROPDOWN` only | At least one `{ label, key? }` object. Rejected for other types |

A `DROPDOWN` field holds one value out of its `options`. An option without a `key` gets one derived from its label, the same way as the field key. Option labels must be unique within the field.

```json
{
  "label": "Lead status",
  "type": "DROPDOWN",
  "options": [{ "label": "Hot" }, { "label": "Cold" }]
}
```

## Key derivation

The `key` is derived from the label: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. `Lead Source` becomes `lead_source`.

A label that resolves to a built-in field key is rejected with `ATTRIBUTE_KEY_RESERVED`. The reserved keys are `name`, `phone_numbers`, `company`, `job_title`, `emails`, `last_activity`, `website`, `created_at` and `updated_at`.

## Response

Returns `201` with the field. `options` is only present for `DROPDOWN`.

```json
{
  "data": {
    "key": "lead_status",
    "label": "Lead status",
    "type": "DROPDOWN",
    "options": [
      { "key": "hot", "label": "Hot" },
      { "key": "cold", "label": "Cold" }
    ],
    "already_existed": false
  }
}
```

## Creating the same field twice

The call is safe to repeat. If a field with the same key and type already exists, the endpoint returns `201` with `already_existed` set to `true` and the label it was first created with. Nothing is created.

If the key exists with a different type, the request returns `409 ATTRIBUTE_KEY_CONFLICT`.

## Restoring a deleted field

Creating a field whose key matches a field you [deleted](/docs/crm/delete-attribute), with the same type, restores it. The values previously stored on people come back with it, and the response has `already_existed` set to `true`. A different type returns `409 ATTRIBUTE_KEY_CONFLICT`.

## Limits

A team can hold up to 150 `TEXT`, 50 `NUMBER`, 30 `DATE` and 30 `BOOLEAN` custom fields. `DROPDOWN` fields count toward the `TEXT` limit. Once a type is full, creating another field of that type returns `409 ATTRIBUTE_SLOTS_EXHAUSTED`.

## Errors

| Status | Code | When |
|--------|------|------|
| `400` | `ATTRIBUTE_LABEL_INVALID` | `label` is blank, longer than 255 characters, or has no letter or digit |
| `400` | `ATTRIBUTE_KEY_RESERVED` | The label resolves to a built-in field key |
| `400` | `ATTRIBUTE_OPTION_INVALID` | A `DROPDOWN` field has no options, or an option label is blank, longer than 255 characters or duplicated |
| `400` | `ATTRIBUTE_OPTIONS_NOT_SUPPORTED` | `options` sent for a type other than `DROPDOWN` |
| `400` | `INVALID_REQUEST_BODY` | `type` is missing or is not one of `TEXT`, `NUMBER`, `DATE`, `BOOLEAN`, `DROPDOWN` |
| `403` | `API_KEY_INSUFFICIENT_SCOPE` | The key does not hold `CRM_WRITE` |
| `404` | `TEAM_NOT_FOUND` | The workspace is not on the new contact model |
| `409` | `ATTRIBUTE_KEY_CONFLICT` | A field with this key already exists with another type |
| `409` | `ATTRIBUTE_SLOTS_EXHAUSTED` | No free slot is left for this type |
