> For the complete documentation index, see [llms.txt](https://learn.withessential.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.withessential.com/administration/settings/add-custom-contact-roles.md).

# Add custom contact roles

Every business starts with four built-in contact roles: Approvals, Scheduling, Onsite, and Billing. Add your own roles to record what else a contact is responsible for at a customer or property. Each custom role gets an icon, and it shows in the same round badge as the built-in roles everywhere contacts appear.

## Before you start

You need permission to edit the Business Profile to add, rename, or delete roles. Anyone who can open Settings can view the page.

To find a role, select the search icon on the right of the **Custom roles** heading and type part of its name.

## Add a role

1. Open **Settings** and select **Contact Roles** under Company.
2. Select **Add contact role**.
3. Select the icon button next to the name to choose an icon. Type in the search box to filter the icons, for example "owner" or "inspection", then select one.
4. Enter a name of up to 40 characters.
5. Select **Save**.

The new role appears in every role picker right away, including the contact **Edit** form, the property's **Contacts** card, and the customer create, merge, and split screens. Assign it like any other role: at the customer level or for specific properties, as primary or secondary.

A custom role can't use a built-in role's name (Approvals, Scheduling, Onsite, Billing) or the picker's own options (All, Primary, Secondary), and two custom roles can't share a name, regardless of capitalization.

## Edit or rename a role

Select the pencil icon on the role's row, change the icon or name, and select **Save**. Renaming a role updates it on every contact that already holds it.

## Delete a role

Select the trash icon on the role's row, then **Delete**. You can only delete a role that no contact holds. The **Contacts** column shows how many contacts hold each role; remove the role from those contacts first, from each contact's **Edit** form.

## How custom roles behave

* The built-in roles can't be renamed, re-iconed, or deleted.
* **All** in the role picker still assigns only the four built-in roles.
* When a property has no contact with the role a message needs (for example, no Approvals contact for a job approval), Essential falls back to another contact with a role there. A contact whose only role is a custom one can be that fallback.
* A custom role gives the contact the same Customer Portal access as a built-in role, when the customer has portal access on.
* In the technician app, custom roles show on the contact but technicians can only change the four built-in roles. Saving a contact in the app keeps its custom roles.

> **Where to find it:** Settings → Company → Contact Roles

## Related guides

* [Contact roles explained](https://learn.withessential.com/customers-and-work/contacts/contact-roles-explained.md)
* [Edit a contact's details, or where their roles live](https://learn.withessential.com/customers-and-work/contacts/edit-a-contacts-details-or-where-their-roles-live.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learn.withessential.com/administration/settings/add-custom-contact-roles.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
