# Custom fields

> Add your own fields to companies, people and opportunities — used on record pages, in tables, lists, reports, workflows, Excel, the REST API and the Claude connector.

When the standard fields are not enough (segment, dealer or not, credit limit, contract end, competitor…), an admin adds fields for companies, people and opportunities in **Settings → Custom fields** ("Ayarlar → Özel alanlar"). Up to 80 fields per object.

## Types

| Type | `type` in the API | Value |
|---|---|---|
| Text | `text` | text (1,000 characters) |
| Long text | `long` | multi-line text |
| Number · Currency · Percent | `number` · `currency` · `percent` | number (currency defined on the field) |
| Date | `date` | `YYYY-MM-DD` |
| Select | `select` | one of the options |
| Multi-select | `multi` | list of options |
| Checkbox | `check` | `true` / `false` |
| Link · Email · Phone | `url` · `email` · `phone` | text (`https://` is added to links, emails are validated) |
| **AI** | `ai` | text or option written by AI — [below](#ai) |

Every field has a permanent **key** (`key`, generated from the name: *Çalışan sayısı* → `calisan_sayisi`, *Yapay zekâ özeti* → `yapay_zeka_ozeti`). The name can change later, the key does not. Deleting a field deletes its values.

## AI fields {#ai}

A field whose value is written by AI rather than by a user. Examples: *Buying temperature* (Hot · Warm · Cold), *Account summary*, *Next best step*.

| Mode | What it writes |
|---|---|
| Summary | The record's current state in a few sentences |
| Classification | One of the options in the definition (at least two) |
| Text to instruction | The answer to your instruction (*"Describe in two sentences what the company buys from us and the risks"*) |

- **Filling:** **Fill / Refresh** under the field on the record page; in a table view select records and use **Fill with AI…** in the bottom bar (up to 200 records per request, filled in turn).
- With **Fill automatically**, empty records are filled by the scheduler (every 10 minutes, 20 records per round); **Refresh every N days** renews ageing values.
- The field is **read-only**: it isn't written by the edit form, imports or the REST API. It's readable, filterable and sortable in tables, usable in workflow conditions, and a classification field can be a report grouping. The workflow *Update field* action can't write to an AI field.
- Under the value the page shows the mode and the time it was last filled.
- The AI module must be in the license and enabled for the organization (Settings → Security). The AI receives a summary of the record (stage, amount, custom fields, company details, contacts' names and titles, recent calls, notes, email subjects); contacts' email addresses and phone numbers are never sent. Every fill counts toward AI usage.

The [AI step](/guides/workflows#ai) in workflows can also write its result into a text or select custom field.

## Where they appear

- **Company and opportunity page** — the *Custom fields* section; **Edit** opens all fields in one form. Numbers are entered in Turkish notation (`1.250` = one thousand two hundred fifty, `3,5`).
- **People** — in the person's edit form on the company page; values are shown briefly on the person row.
- [Migrating from Salesforce](/guides/salesforce-migration) opens Salesforce fields as custom fields (with an *SF* badge) and can write into an existing field with the same name.
- **Table views and lists** — added as columns, used in filters and sorting, kanban can group by a select field, bulk updates. On the Customers and Opportunities pages the *Custom fields* button adds personal columns, a filter and sorting too. [Table views and lists](/guides/views-and-lists)
- **Excel** — columns in the Customers, Opportunities (with company fields), table view and list exports; matched by header name when [importing](/guides/import).
- **Report builder** — group and filter by select / checkbox / text fields, sum and average of number / currency / percent fields; opportunity reports can use the company's fields as well.
- **Workflows** — in conditions (opportunity and company fields) and in the *Update field* action.

## REST API

Company, person and opportunity records return a `custom_fields` array (when fields are defined):

```json
"custom_fields": [
  {"key": "segment", "label": "Segment", "type": "select", "value": "A Segmenti"},
  {"key": "calisan_sayisi", "label": "Çalışan sayısı", "type": "number", "value": 1250.0},
  {"key": "bayi", "label": "Bayi", "type": "check", "value": true}
]
```

To write, put a `custom_fields` object in the body — use the key **or** the name:

```json
PATCH /api/v1/customers/42
{"custom_fields": {"segment": "B Segmenti", "Çalışan sayısı": 1300, "bayi": false}}
```

Accepted on: `POST /api/v1/customers`, `PATCH /api/v1/customers/{id}`, `POST /api/v1/customers/{id}/contacts`, `PATCH /api/v1/contacts/{id}`, `POST /api/v1/opportunities`, `POST /api/v1/opportunities/{id}/fields`.

- Send numbers as JSON numbers; strings such as `"3,45"` and `"1.250,50"` are parsed too.
- An empty string or `null` clears the value.
- An unknown field or invalid value does not block the request; the response carries a `custom_field_errors` list (e.g. `"bilinmeyen özel alan: yok_boyle"` — unknown custom field).

## MCP (Claude)

The `create_company`, `update_company`, `create_contact` and `create_opportunity` tools take a `custom_fields` parameter; its description lists the installation's fields with their types and options, so Claude uses the right key and value. Read tools (`get_company`, `get_opportunity`) return the values.