# Overview

> Manage custom contact fields in your Allo CRM

Custom fields add your own data to people, such as a lead source or a budget. The Custom fields API lets you list, create, edit and delete the fields defined on your team.

## Scopes

| Scope | Access |
|-------|--------|
| `CRM_READ` | List custom fields, and read `custom_attributes` on people |
| `CRM_WRITE` | Create and edit custom fields, and set `custom_attributes` on people |
| `CRM_DELETE` | Delete custom fields |

## Define a field, then set its value

A custom field is only the definition. The values live on each person, under `custom_attributes`.

1. Define the field with [Create custom field](/docs/crm/create-attribute), for example `Lead Source` of type `TEXT`. Note the `key` it returns, here `lead_source`.
2. Set its value with `custom_attributes` on [Create person](/docs/crm/create-person) or [Update person](/docs/crm/update-person): `{ "custom_attributes": { "lead_source": "Webinar" } }`.
3. Read it back from `custom_attributes` on [Get person](/docs/crm/get-person) and [Search people](/docs/crm/search-people).

Only the keys you send are written, and `null` clears a value. Key and type errors come back as `CUSTOM_ATTRIBUTE_KEY_UNKNOWN` and `CUSTOM_ATTRIBUTE_VALUE_INVALID`. People responses always include `custom_attributes`, with archived fields and empty values left out. Search cannot filter or sort on custom fields.

## Field types

| Type | Notes |
|------|-------|
| `TEXT` | |
| `NUMBER` | |
| `DATE` | |
| `BOOLEAN` | |
| `DROPDOWN` | One value out of a fixed list of `options`, each with a `key` and a `label`. Fields synced from your CRM integrations can also be dropdowns. |

## Keys

Each field has a `key`, derived from its label: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. `Lead Source` becomes `lead_source`.

## Limits

A team can hold up to 150 `TEXT`, 50 `NUMBER`, 30 `DATE` and 30 `BOOLEAN` custom fields. `DROPDOWN` fields count toward the `TEXT` limit. Creating a field beyond the limit for its type returns `ATTRIBUTE_SLOTS_EXHAUSTED`.

## Editing and deleting fields

[Update custom field](/docs/crm/update-attribute) changes the label, the description and the options of a dropdown. The `key` and the `type` never change. Fields synced from a CRM integration cannot be edited or deleted, and built-in fields such as `name` or `company` are not custom fields.

<Note>
Deleting a person field is not the same as deleting a company attribute. [Delete custom field](/docs/crm/delete-attribute) removes the field from the API but keeps the values stored on people, and creating a field with the same label and type restores it with them. [Delete company attribute](/docs/crm/delete-company-attribute) clears the values on every company and cannot be undone.
</Note>

Custom fields are available on workspaces that use the new contact model. Other workspaces get a `404 TEAM_NOT_FOUND`.

## Endpoints

<CardGroup cols={1}>
  <Card title="List custom fields" href="/docs/crm/list-attributes">List the custom fields of your people</Card>
  <Card title="Create custom field" href="/docs/crm/create-attribute">Create a custom field</Card>
  <Card title="Update custom field" href="/docs/crm/update-attribute">Edit a custom field</Card>
  <Card title="Delete custom field" href="/docs/crm/delete-attribute">Delete a custom field</Card>
</CardGroup>
