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

# Add your own contact fields

> Create custom contact fields in Brilo so your agent knows each customer appointment date, balance, or account number, and your campaign emails can use them as variables.

Custom fields are how a campaign stops sounding generic. A field called `appointment_date` on the contact
lets one email step say "your appointment on Thursday the 14th" to every recipient, each with their own
date. Your agent can read them on a call too.

Fields are defined once for your whole workspace, then filled in per contact.

## Before you start

* Ten minutes.
* A list of the things you find yourself needing on a call that Brilo does not already hold.
* Your import file to hand, if you are creating fields so you can import a column into them.

## Steps

<Steps>
  <Step title="Work out what you actually need">
    The test is simple: would your agent say it out loud, or would an email step insert it? If neither, it
    does not need to be a field.

    Four or five fields covers most businesses. Twenty means you are rebuilding your CRM inside Brilo.
  </Step>

  <Step title="Create the field">
    Go to your contacts settings and add a custom field. Give it a clear key, because that key is what you
    use in campaign emails and prompts.

    Name it after the thing: `appointment_date`, `amount_owed`, `policy_number`. Not
    `field_1` and not `when_is_their_appointment`.
  </Step>

  <Step title="Pick the right type">
    | Type             | Use it for                                                  |
    | ---------------- | ----------------------------------------------------------- |
    | **Text**         | Names, references, anything freeform                        |
    | **Number**       | Amounts, quantities, counts                                 |
    | **Date**         | Appointment dates, renewal dates                            |
    | **Datetime**     | When the time of day matters as well                        |
    | **Email**        | A second address, or an account owner's address             |
    | **Phone**        | An alternative number                                       |
    | **URL**          | A booking link or a portal link specific to that customer   |
    | **Boolean**      | Yes or no facts, like whether they are a returning customer |
    | **Multi select** | One of a fixed set of options, or several                   |

    The type is enforced on import, so text in a number field is rejected rather than quietly stored.
    Choosing **Text** for everything avoids rejections and costs you that protection.
  </Step>

  <Step title="Fill the values">
    Either import them as columns alongside your contacts, or edit a contact directly. See
    [Import your contact list](/contacts/import-your-contact-list).
  </Step>

  <Step title="Use them">
    In a campaign email, insert the variable with the **+** button. In an agent prompt, refer to the field
    so your agent knows to use it. Then send one test to yourself and check the value appears.
  </Step>
</Steps>

## You will know it worked when

A test campaign email to your own address arrives with your own appointment date in it, not a blank space
and not the raw variable name.

## Using fields in campaign emails

Custom fields are available as `{{custom.<key>}}`, where the key is the one you set. A field with the key
`appointment_date` is `{{custom.appointment_date}}`.

Insert them with the **+** button in the email editor rather than typing them, so the key is always
correct. They work in the subject, the body, and in **Cc** and **Bcc**, which is how you copy in the
account owner for each contact rather than one fixed colleague. See
[Add an email step](/campaigns/email-step).

## Fields worth creating for campaigns

| Field                 | Type         | What it unlocks                                          |
| --------------------- | ------------ | -------------------------------------------------------- |
| `appointment_date`    | Date         | Reminders that name the date                             |
| `amount_owed`         | Number       | Invoice chases that state the figure                     |
| `invoice_number`      | Text         | A payment call the customer can actually match to a bill |
| `service`             | Multi select | An opening line about the right product                  |
| `account_owner_email` | Email        | Emails Cc'd to the right colleague                       |
| `booking_link`        | URL          | A text with a link personal to them                      |

Each one turns a generic step into a specific one, and specific steps get answered.

## Always test with an empty value

The failure nobody catches: a contact who has no value for the field. Your email arrives with a gap in the
middle of a sentence and reads as obviously automated, which undoes the whole point.

Before a big send, add a test contact with the field deliberately empty and read what arrives. Then write
the sentence so it survives a blank, or make sure every contact has a value.

## What else you can do here

* Have your agent collect and confirm these details on the call, so they fill themselves in. See
  [Write what your agent says](/agents/write-what-your-agent-says).
* Capture them from the conversation automatically as extraction fields. See
  [Pull the details out of every call](/reports/extract-call-information).
* Let your agent recognise returning callers and use what it holds. See
  [Remember callers between calls](/agents/remember-callers).
* Push values into your own CRM after the call. See [Update your CRM](/actions/update-your-crm).

## If it did not work

**The variable printed as raw text in the email.** The key does not match a field that exists. Insert
variables with the **+** button rather than typing them.

**The variable came out blank.** That contact has no value for the field. Test with an empty contact before
you send to a list.

**Values were dropped on import.** They failed the field's type validation, or the key does not exist or was
archived. Unknown, archived, and reserved keys are dropped and reported, and the contact is still created.

**Your agent does not use the field on calls.** It has the value but was never told to use it. Mention the
field in the agent's instructions.

**You cannot change a field's type.** Create a new field with the right type and migrate. Changing a type
under existing data is not something to do casually.

## FAQ

<AccordionGroup>
  <Accordion title="Can I add custom fields to Brilo contacts?">
    Yes. Create them once for your workspace, choosing a type such as text, number, date, email, phone,
    URL, boolean, or multi select. They can then be imported per contact and used in agent prompts and
    campaign emails.
  </Accordion>

  <Accordion title="How do I use a custom field in a campaign email?">
    Insert it with the **+** button in the email editor. Custom fields are available as
    `{{custom.<key>}}`, and they work in the subject, the body, and in Cc and Bcc.
  </Accordion>

  <Accordion title="What field types are available?">
    Text, number, date, datetime, email, phone, URL, boolean, and multi select. The type is enforced on
    import, so a value that does not fit is rejected rather than quietly stored wrong.
  </Accordion>

  <Accordion title="Why did my custom field values get dropped on import?">
    They failed validation for that field's type, or the key was unknown, archived, or reserved. The
    dropped values are reported and the contact is still created, so check the report rather than the
    contact count.
  </Accordion>

  <Accordion title="What happens if a contact has no value for a field?">
    The variable comes out blank, leaving a gap in your sentence. Always send a test to a contact with the
    field empty before a large send.
  </Accordion>

  <Accordion title="Can my agent read custom fields during a call?">
    Yes, and mentioning the field in the agent's instructions is what makes it actually use one. Turn on
    **Contact Memory** so it recognises the caller in the first place. See
    [Remember callers between calls](/agents/remember-callers).
  </Accordion>

  <Accordion title="How many custom fields should I create?">
    Four or five for most businesses. The test is whether your agent would say it out loud or an email
    would insert it. Anything else belongs in your CRM, not here.
  </Accordion>
</AccordionGroup>

## Related

* [Import your contact list](/contacts/import-your-contact-list) to fill the fields in bulk
* [Add an email step](/campaigns/email-step) for using them as variables
* [Pull the details out of every call](/reports/extract-call-information) to capture them from calls
* [Remember callers between calls](/agents/remember-callers) so your agent uses them
* [Update your CRM](/actions/update-your-crm) to send values back to your own system