Extending the CiviCRM Database - Creating Custom Data Fields

Understanding Custom Data Fields

CiviCRM comes pre-populated with many of the data fields that are standard for contact management and non-profit organizations (see What is a field? for a definition). For example:

  • for Contacts: Name, Email, Phone, and Address
  • for Contributions: Contribution Type, Total Amount, Receipt Date, and Notes
  • for Events: Events Type, Participant Role, Event Title, and Event Start/End Dates

In addition to pre-built data fields, CiviCRM gives you the power to customize your information via custom data fields – fields that are defined and built by you to record and collect information specific to your organization.

For example, you can provide a series of check-boxes on your volunteer form that allows them to indicate what skills they have, or include a field that records the days of the week they are available or whether they've read and signed a liability waiver.

Working with Custom Data

Custom data fields are stored in CiviCRM in custom field sets. Because of this, you must add custom data in a two-step process:

  1. Create a custom field set that is associated with objects such as Events, Organization, Individual, Participant Roles, even Contact Sub-types such as Individual:Board Member (you must create the Board Member sub-type first).
  2. Create and add custom fields to this set.

Designing and building custom data requires some forethought about how you will want to use the data. It is also one of the primary ways that you can extend the capabilities of CiviCRM and tailor it for your organization. For more in-depth discussion on how and when to use Custom Data and explanations for each of the Used for and Data Types, see the CiviCRM Online Book discussing Custom Data Fields.

Create a Custom Data Set

  1. In the Administration Menu across the top of your page, select Administer → Custom Data and Screens → Custom Fields. The Custom Data page now appears.
  2. Click the Add Set of Custom Fields button. The New Custom Field Set page now appears.
  3. Enter a name for the field set in the Set Name field.
  4. Select the CiviCRM object that this data group will be associated with in the Used For drop-down. For example, Activities, Contributions, Contacts, Individuals, etc.

    The number of fields on this form may change according to the type of object you select. For example, if you select Activities you will see a select box for the type of activity; if you select Contacts you will see an additional check-box for multiple records and an additional drop-down for the Display Style.

    NOTE: The option "Contacts" bridges all contact types: Individual, Household or Organization.
    NOTE: For help with any field in CiviCRM, click the icon to the right of the field (if available).
  5. Enter a number in the Order field. The Order field determines the placement of the field set in the main list if there is more than one set.
  6. If you want the field set collapsed, check the check-boxes for Collapse this group on initial display and Collapse this group in Advanced Search.
  7. Make sure that Is this Custom Data Group Active is checked.
  8. Enter instructions in the Pre-form and Post-form Help WYSIWYG editors, if necessary/desired. These instructions will appear when admin users are working on the data on a form within CiviCRM. These instructions will not apply to profile forms that are viewed by front-end users (Instructions for end-users are included on the Profile).
  9. Click the Save button to save the group.

You will now see a Custom Data Field page where you can enter your first custom data field.

Create Custom Data Fields

On the Custom Data Field page:


The number of fields on this form may change according to the type of data and input Field Types you select. For example, if you select Alphanumeric/Radio you will see a section for Multiple Choice Options where you can enter the values for the radio buttons. For more in-depth explanation on each field type and what it does, see the CiviCRM Online Book on Custom Data Fields. Scroll down to the middle of the page where the book discusses Custom Data → Types.

CiviCRM Custom Data Fields

  • Complete the form based on the form fields for your data and input types.
  • Check Required? if the user must enter information into this field. Remember that this will force all users to enter data into this field.
  • Check Is this Field Searchable? if you want to use this field for searching purposes. For example, you want to be able to search on the field in the Find Contacts - Advanced Search.
  • Make sure the Active? field is checked.
  • Click the Save button to save the field or the Save and New button to save the field and create another.
  • Repeat this process for all the fields necessary for your field set.

Your custom data fields are now available. You will automatically see custom data fields reflected in the element that the set is used for (i.e., Contributions, Contacts, Events, Activities, etc.). To use the custom data fields in a form on your website, you must create a Profile that houses the fields and can be exposed through the website. For more information on using Profiles continue to the next section, Profiles.