> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom attributes

> Define firm-specific fields Metal tracks on companies, deals, people, and activities, including field keys, types, and how edits behave.

Custom attributes are firm-defined fields Metal tracks alongside the built-in schema. Use them to capture the data your firm cares about that isn't in Metal's default model — a proprietary score, a source tag, a due-diligence flag — and have it show up on records the same way built-in fields do.

Custom attributes are admin-gated and live under **Firm Knowledge**. Open **Settings → Custom Attributes**.

## Which objects support custom attributes

Attributes are defined per object type. Metal supports four:

* **Companies**
* **Deals**
* **People**
* **Activities**

The settings page has a tab for each. Switching tabs shows the fields defined on that object type.

<Note>
  If a tab shows "Custom attributes for … aren't available on this environment yet," the backend hasn't rolled out that object type here. Try again later or contact [support@metal.ai](mailto:support@metal.ai).
</Note>

## Anatomy of a field

Each custom attribute has:

| Property                | Notes                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **Field name**          | The base name you type when creating the field, e.g. `acme`.                        |
| **Type**                | One of `string`, `number`, `boolean`, `array`, or `object`.                         |
| **Field key**           | The stored key. Metal appends a type suffix to your base name (see below).          |
| **Display name**        | What teammates see in the app, e.g. "Acme Score".                                   |
| **Description**         | Optional short explanation of what the field means.                                 |
| **Rendering component** | Optional hint for how the app should render the value (for example, `date-picker`). |
| **Indexed**             | Whether Metal indexes the field for filtering and search.                           |

### Field-key suffix convention

The stored key always ends with a suffix that matches the type. Metal builds the key for you from your base name and the type you pick:

| Type      | Suffix | Example key (base `acme`) |
| --------- | ------ | ------------------------- |
| `string`  | `Str`  | `acmeStr`                 |
| `number`  | `Num`  | `acmeNum`                 |
| `boolean` | `Bool` | `acmeBool`                |
| `array`   | `Arr`  | `acmeArr`                 |
| `object`  | `Obj`  | `acmeObj`                 |

Legacy `date` fields use the `Date` suffix. You can still edit an existing `date` field, but you cannot create a new one from the app.

The key preview updates as you type the base name in the create dialog.

Base names must be non-empty, cannot start with an underscore, and cannot contain whitespace or the characters `.`, `$`, or `/`. Keys are unique per object type (case-insensitive).

## Create a field

<Steps>
  <Step title="Open Custom Attributes">
    Go to **Settings → Custom Attributes** and pick the tab for the object type you want to extend.
  </Step>

  <Step title="Click Create Field">
    Enter a **Field Name** (the base name — Metal appends the type suffix), pick a **Type**, and set a **Display Name**. Add an optional **Description** and **Rendering Component** if relevant, and toggle **Indexed** if you'll filter or search on the field.
  </Step>

  <Step title="Create">
    Metal writes the field to the object's schema. New records — and existing records that get updated — can store values under the new key.
  </Step>
</Steps>

<Tip>
  Nested definitions for `array` items and `object` fields aren't editable from the dialog. Create the field with type `array` or `object`, then manage the nested shape through the API.
</Tip>

## Edit a field

Click the pencil icon on a row to change the display name, description, rendering component, or indexed setting. The field key itself is fixed once created — except when you change the type.

### Changing the type is a re-key

Because the key must match the type suffix, changing a field's type means creating a new key and removing the old one. Metal walks you through this:

1. Metal generates the new key by swapping the suffix — e.g. `acmeStr` → `acmeNum` when you change `string` to `number`.
2. You confirm the change in the "Change field type?" dialog.
3. The new field is created first; the old key is then deleted.

If Metal cannot remove the old key, both fields remain until you delete the old one manually.

Values previously stored under the old key stay on individual records but no longer match the new field, so they stop appearing in the app. In practice, treat a type change as a fresh field — plan to re-populate values on records that need them.

<Warning>
  A type change is not a data migration. Stored values are not converted; they're orphaned under the old key.
</Warning>

## Delete a field

Click the trash icon on a row to remove a custom attribute. Deleting a field removes it from the schema so it no longer appears in the app, but values previously written to individual records are left in place, orphaned. Re-creating a field with the same key surfaces those values again.

## Where custom attributes show up

Once defined, custom attributes behave like other fields on their object type — they can be read and written through the Metal API and referenced in workflows, enrichment, and dashboards. Indexed attributes are additionally available as filters and in search.


## Related topics

- [Workspace settings](/help/admin/settings.md)
- [Financial metrics](/concepts/financial-metrics.md)
- [Enrichment](/concepts/enrichment.md)
- [Update a company](/api-reference/companies/update-a-company.md)
- [Create a company](/api-reference/companies/create-a-company.md)