---
name: "crm_define_field"
area: "crm"
title: "Define a custom field"
price: "$0.001"
method: "POST"
url: "https://api.conecto.chat/v1/tools/crm_define_field"
mcp_server: "https://api.conecto.chat/mcp/crm"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/crm/crm_define_field"
---

# Define a custom field (`crm_define_field`)

Adds a field of the business's own to contacts, companies or deals, or changes its label, description or options.

Add a field of your own to contacts, companies or deals, such as a "plan" picked from a list or a "renewal_date", or change its label, description or options. From then on values sent in custom_fields are checked against its type (text, number, boolean, date as YYYY-MM-DD, select from options, url, email, phone), and you can filter and sort on it. A field that holds values keeps its type; delete it and define it again to change the type.

Price: $0.001 a call. A call that fails costs nothing.

## Use it when

The business tracks something the standard fields lack: a trade tier, a renewal date, a preferred wood.

## Say this to your agent

> Add a trade tier to companies, Silver or Gold, so we know who gets 10% and who gets 15%.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `object` | string | yes |  | `"contact"`, `"company"`, `"deal"` |  |
| `key` | string | yes | snake_case, e.g. "renewal_date" (matches ^[a-z][a-z0-9_]{0,39}$) |  |  |
| `type` | string | yes |  | `"text"`, `"number"`, `"boolean"`, `"date"`, `"select"`, `"url"`, `"email"`, `"phone"` |  |
| `label` | string | no | Up to 80 characters. |  |  |
| `options` | array of strings | no | select only: the allowed values (up to 100 items) |  |  |
| `description` | string | no | What the field means, for whoever reads it next. Up to 300 characters. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `crm_define_field` on the MCP server `https://api.conecto.chat/mcp/crm` with these arguments:

```json
{
  "object": "company",
  "key": "trade_tier",
  "type": "select",
  "label": "Trade tier",
  "options": [
    "Silver",
    "Gold"
  ],
  "description": "Discount of a trade account: Silver 10%, Gold 15%."
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/crm_define_field \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object": "company", "key": "trade_tier", "type": "select", "label": "Trade tier", "options": ["Silver", "Gold"], "description": "Discount of a trade account: Silver 10%, Gold 15%."}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "crm_define_field",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.001",
  "balance_usd": "$19.75",
  "result": {
    "field": {
      "object": "company",
      "key": "trade_tier",
      "label": "Trade tier",
      "type": "select",
      "options": [
        "Silver",
        "Gold"
      ],
      "description": "Discount of a trade account: Silver 10%, Gold 15%.",
      "created_at": "2026-10-14T08:00:00+00:00"
    },
    "created": true
  }
}
```

`result`: The field (object, key, type, label, options, description), and created: true when it is new.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | The key is a standard field, a select field has no options, or another type was given options. | Pick another key, and give options only to select fields. |
| `conflict` | 409 | The field holds values and the type would change, or it was defined at the same moment. | Delete it with crm_delete_field and define it again, or call again. |
| `limit_reached` | 409 | The object has as many custom fields as it may. | Delete a field it no longer needs with crm_delete_field. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [crm_search](https://conecto.chat/tools/crm/crm_search.md): Finds contacts, companies and deals from whatever you have: a name, an email, a phone number in any format, a domain or a deal title. Free up to 1,000,000 reads a month.
- [crm_find_contacts](https://conecto.chat/tools/crm/crm_find_contacts.md): Finds contacts by name, email, company or phone, by filters on any field or tag, or by a saved segment, one page at a time. Free up to 1,000,000 reads a month.
- [crm_get_contact](https://conecto.chat/tools/crm/crm_get_contact.md): One contact, by id or email, with its tags, custom fields, recent activity, open tasks and deals. Free up to 1,000,000 reads a month.
- [crm_get_customer](https://conecto.chat/tools/crm/crm_get_customer.md): Everything open with one customer in one read: deals, tickets, invoices, quotes, signatures, meetings and their last messages. Free up to 1,000,000 reads a month.
- [crm_save_contact](https://conecto.chat/tools/crm/crm_save_contact.md): Creates a contact, or updates the one with the same email; only the fields you send change. $0.01 a call.
- [crm_save_contacts](https://conecto.chat/tools/crm/crm_save_contacts.md): Creates or updates up to 100 contacts in one call, each like crm_save_contact; you pay only for the ones saved. $0.01 per record saved.
- [crm_update_contact](https://conecto.chat/tools/crm/crm_update_contact.md): Changes fields on a contact by its id, its email included; only the fields you send change. $0.01 a call.
- [crm_archive_contact](https://conecto.chat/tools/crm/crm_archive_contact.md): Hides a contact from searches and lists; its history is kept. $0.001 a call.
- [crm_restore_contact](https://conecto.chat/tools/crm/crm_restore_contact.md): Brings an archived contact back into searches and lists. $0.001 a call.
- [crm_timeline](https://conecto.chat/tools/crm/crm_timeline.md): What happened with a contact, a company, a deal or the whole CRM, newest first: notes, tasks, emails, chats, calls, tickets and stage moves. Free up to 1,000,000 reads a month.
- [crm_add_note](https://conecto.chat/tools/crm/crm_add_note.md): Adds a note to a contact, a company or a deal: what was said, decided or learned. $0.01 a call.
- [crm_create_task](https://conecto.chat/tools/crm/crm_create_task.md): A follow-up on a contact, with an optional due time and priority. $0.01 a call.
- [crm_list_tasks](https://conecto.chat/tools/crm/crm_list_tasks.md): Tasks by status (open by default), for one contact or due before a time, soonest first. Free up to 1,000,000 reads a month.
- [crm_complete_task](https://conecto.chat/tools/crm/crm_complete_task.md): Marks a task done, or cancelled. $0.01 a call.
- [crm_save_company](https://conecto.chat/tools/crm/crm_save_company.md): Creates a company, or updates the one with the same name or with the company_id you give, which can rename it; only the fields you send change. $0.01 a call.
- [crm_save_companies](https://conecto.chat/tools/crm/crm_save_companies.md): Creates or updates up to 100 companies in one call, each like crm_save_company; you pay only for the ones saved. $0.01 per record saved.
- [crm_archive_company](https://conecto.chat/tools/crm/crm_archive_company.md): Hides a company from lists, searches, duplicates and exports; its people, deals and notes stay. $0.001 a call.
- [crm_restore_company](https://conecto.chat/tools/crm/crm_restore_company.md): Brings an archived company back into lists, searches, duplicates and exports. $0.001 a call.
- [crm_find_companies](https://conecto.chat/tools/crm/crm_find_companies.md): Finds companies by name or domain, by filters on any field or tag, or by a saved segment, one page at a time. Free up to 1,000,000 reads a month.
- [crm_get_company](https://conecto.chat/tools/crm/crm_get_company.md): One company, by id or exact name, with its people, deals (open ones first) and notes. Free up to 1,000,000 reads a month.
- [crm_save_deal](https://conecto.chat/tools/crm/crm_save_deal.md): Creates a deal, or updates one by its deal_id: pipeline and stage, amount, close date, next step, company and contact. $0.01 a call.
- [crm_find_deals](https://conecto.chat/tools/crm/crm_find_deals.md): Finds deals by pipeline, stage, status, company or contact, by filters on any field or tag, or by a saved segment. Free up to 1,000,000 reads a month.
- [crm_get_deal](https://conecto.chat/tools/crm/crm_get_deal.md): One deal with its stage history (the days it spent in each stage), notes, contact and company. Free up to 1,000,000 reads a month.
- [crm_move_deal](https://conecto.chat/tools/crm/crm_move_deal.md): Moves a deal to a stage, maybe in another pipeline; a won or lost stage closes it. $0.01 a call.
- [crm_list_pipelines](https://conecto.chat/tools/crm/crm_list_pipelines.md): The deal pipelines in order, each with its stages and how many deals sit in each, with their value. Free up to 1,000,000 reads a month.
- [crm_save_pipeline](https://conecto.chat/tools/crm/crm_save_pipeline.md): Creates a deal pipeline or changes one: its name, position and stages in order. $0.001 a call.
- [crm_delete_pipeline](https://conecto.chat/tools/crm/crm_delete_pipeline.md): Deletes an empty pipeline; the last one stays. $0.001 a call.
- [crm_pipeline_report](https://conecto.chat/tools/crm/crm_pipeline_report.md): How a pipeline is doing: open value by stage, deals won and lost, win rate, a forecast by month and stale deals. Free up to 1,000,000 reads a month.
- [crm_list_fields](https://conecto.chat/tools/crm/crm_list_fields.md): The standard and custom fields of contacts, companies and deals, to read, filter and sort on. Free up to 1,000,000 reads a month.
- [crm_delete_field](https://conecto.chat/tools/crm/crm_delete_field.md): Deletes a custom field and its value on every record, for good. $0.001 a call.
- [crm_tag_records](https://conecto.chat/tools/crm/crm_tag_records.md): Adds and removes tags on up to 100 contacts, companies or deals at once. $0.001 per record tagged.
- [crm_list_tags](https://conecto.chat/tools/crm/crm_list_tags.md): Every tag with how many contacts, companies and deals carry it. Free up to 1,000,000 reads a month.
- [crm_delete_tag](https://conecto.chat/tools/crm/crm_delete_tag.md): Deletes a tag and takes it off every contact, company and deal. $0.001 a call.
- [crm_save_segment](https://conecto.chat/tools/crm/crm_save_segment.md): Saves filters under a name, so the same list can be pulled again and stays up to date. $0.001 a call.
- [crm_list_segments](https://conecto.chat/tools/crm/crm_list_segments.md): The saved segments, each with its filters and how many records match right now. Free up to 1,000,000 reads a month.
- [crm_delete_segment](https://conecto.chat/tools/crm/crm_delete_segment.md): Deletes a saved segment; the records in it stay as they are. $0.001 a call.
- [crm_export](https://conecto.chat/tools/crm/crm_export.md): Contacts, companies or deals as CSV text, with the same filters, tag and segment as the find tools. Free up to 1,000,000 reads a month.
- [crm_find_duplicates](https://conecto.chat/tools/crm/crm_find_duplicates.md): Contacts or companies that are probably the same record twice, grouped, with the reason. Free up to 1,000,000 reads a month.
- [crm_merge_contacts](https://conecto.chat/tools/crm/crm_merge_contacts.md): Merges duplicate contacts into the one you keep; their notes, emails, chats, calls and deals move with them. $0.01 a call.
- [crm_merge_companies](https://conecto.chat/tools/crm/crm_merge_companies.md): Merges duplicate companies into the one you keep; their people, deals and notes move with them. $0.01 a call.