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

# Custom fields

> Add your own fields to nine record types, fill them on the record's form, and filter and sort lists by them.

Custom fields let an admin add the data your business tracks, for example a domain renewal date on projects, a referral source on quotes or a policy number on contacts. Every field is stored on the record itself, keyed by its immutable `key`.

## Where fields live

Settings → CRM → **Custom fields** ("שדות מותאמים"). There is one tab per record type:

| Entity | Key | Where you fill it |
| - | - | - |
| Clients | `client` | The client card |
| Leads | `lead` | The lead card |
| Projects | `project` | The project card |
| Contacts | `contact` | The contact dialog on the client card |
| Quotes | `quote` | The quote editor (and the quote page after sending) |
| Tickets | `ticket` | The ticket page and the new ticket dialog |
| Tasks | `task` | The task drawer |
| Expenses | `expense` | The expense dialog |
| Services | `service` | The service dialog in the catalog |

## Types

| Type | Value in the API | Notes |
| - | - | - |
| `text` | string | Up to 1,000 characters |
| `long_text` | string | Up to 10,000 characters, line breaks kept |
| `number` | number | |
| `money` | integer agorot | `12345` is ₪123.45 |
| `date` | `YYYY-MM-DD` | |
| `select` | string | One of the field's options |
| `multi_select` | string\[] | Stored in the options' order |
| `checkbox` | boolean | |
| `url` | string | `http` or `https` only |
| `phone` | string | Normalized to the local form (`0501234567`) |
| `email` | string | Stored in lower case |
| `user` | user id | Must be a member of the organization |
| `rating` | integer 1-5 | |
| `file` | file id | A ready file attached to the record or to its client / project. Not available on leads and services, which have no files |
| `formula` | number | Read-only: computed by Lancer, never written by clients |

`null` or an empty string clears a value. Unknown keys are rejected with `400`.

## Definition settings

* **Group**: fields of the same group show together, in a collapsible section of the form.
* **Required**: a new record must have a value (also when an API call leaves `customFields` out); editing an older record only checks the fields you change.
* **Help text** under the input, and a **default value** for new records.
* **Visibility**: `staff`, `portal` or `public_form` (who may see the field).
* **Validation**: `min` / `max` for numbers and amounts, `maxLength` and `pattern` (a regular expression) for text.

### Formulas

A formula is a small, safe expression: numbers, `+ - * /`, parentheses, the record's numeric fields as `{key}` (number, amount and rating; amounts in shekels), a few built-in record numbers (for example `budget` on projects, `total` on quotes, `amount` on expenses), and the functions `round(x, digits)`, `min`, `max` and `if(condition, a, b)` with comparisons (`<`, `<=`, `>`, `>=`, `==`, `!=`). Example: `round(budget / {hours}, 2)`. A formula that cannot be computed (a missing value, division by zero) has no value.

### Amounts and hidden finance

Team members whose finance is hidden, and contractors, do not see amount fields or formulas that read an amount (such as `budget`), cannot filter or sort by them, and cannot change them.

## Filter and sort lists

Every list of these nine entities accepts two query parameters:

* `cf`: a JSON object of `{ key: value }`. Text, long text, link, phone and email match by **contains**; select and team member by **equality** (or a list for any-of); a checkbox by `true` / `false`; a multi-select by **any of** a list; number, amount, rating, formula and date by equality or a range `{ "min": …, "max": … }` (inclusive).
* `cfSort`: `key:asc` or `key:desc`. Numbers, amounts, ratings and formulas sort numerically, dates by date, everything else as text. Records without a value come last either way.

```bash theme={null}
curl -G "https://api.lancer-erp.com/api/projects" \
  --data-urlencode 'cf={"renewal":{"min":"2026-12-01","max":"2026-12-31"}}' \
  --data-urlencode 'cfSort=renewal:asc'
```

## Archive and delete

Deleting a field **archives** it: it leaves the forms and filters, but the values stay on the records, in their history and in exports, and you can restore it. **Delete permanently** ("מחיקה לצמיתות", archived fields only, after a confirmation) removes the values from every record.

Your plan limits how many **active** fields the organization has across all entities; archived fields do not count.

## Events

Creating, editing and archiving a field emit `custom_field.created`, `custom_field.updated` and `custom_field.archived`, and each change lands in the audit log under settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.