# Create company attribute

> Creates a custom attribute on your team's companies. The key is derived from the label. The call is idempotent: if an attribute with the same key and type…

`POST /v2/api/crm/companies/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 |
| `prompt` | string | no | Instruction the AI CRM Manager follows to fill this attribute from calls |
| `should_prompt_override` | boolean | no | Whether the AI may overwrite a value that is already set |

## Key derivation

The `key` is derived from the label: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. `Industry segment` becomes `industry_segment`. Option keys are derived the same way.

A label that resolves to a reserved key is rejected with `ATTRIBUTE_KEY_RESERVED`. The reserved keys are: `id`, `name`, `phone_numbers`, `website`, `industry`, `logo_url`, `last_activity`, `activity_history`, `sms_content`, `created_at` and `updated_at`.

## Response

Returns `201` with the created attribute. `source` is `allo`, and `already_existed` is `false`.

```json
{
  "data": {
    "key": "industry_segment",
    "label": "Industry segment",
    "type": "DROPDOWN",
    "options": [
      { "key": "smb", "label": "SMB" },
      { "key": "enterprise", "label": "Enterprise" }
    ],
    "is_visible": true,
    "prompt": "Pick the segment that matches the company size mentioned on the call.",
    "should_prompt_override": false,
    "source": "allo",
    "created_at": "2026-10-07T14:21:08",
    "updated_at": "2026-10-07T14:21:08",
    "already_existed": false
  }
}
```

## Creating the same attribute twice

The call is safe to repeat. If an attribute with the same key and type already exists, the endpoint returns `201` with that attribute and `already_existed` set to `true`. Nothing is created and the existing definition is left unchanged. If the key exists with a different type, the request returns `409 ATTRIBUTE_KEY_CONFLICT`.

## Limits

Each type has a fixed number of slots per team. Once a type is full, creating another attribute of that type returns `409 ATTRIBUTE_SLOTS_EXHAUSTED`. Delete an unused attribute or use another type.

Custom attributes are only available to teams on the new contact model. Other teams get `404 TEAM_NOT_FOUND`.

## 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 reserved key |
| `400` | `ATTRIBUTE_OPTION_INVALID` | A `DROPDOWN` attribute 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 unknown |
| `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` | An attribute with this key already exists with another type |
| `409` | `ATTRIBUTE_SLOTS_EXHAUSTED` | No free slot is left for this type |
| `409` | `ATTRIBUTE_CONCURRENT_MODIFICATION` | Attributes were modified at the same time. Retry the request |
