# Database ### Overview The database is at the heart of UbiQuity. It has a flat structure, similar to a spreadsheet, where each row is a contact and each column is a field. You define the fields yourself, which means you can structure your database to suit your organisation and the data you collect. Each UbiQuity account has one database. If you need a separate database for a different purpose, you would need a separate account. The database is required if you are using UbiQuity Email or Forms. It is optional for Surveys, Events, TXT, and Push Messaging, though connecting these to your database unlocks filtering and personalisation across those modules. UbiQuity automatically records activity against each contact as it happens — emails sent, opened and clicked, form submissions, survey responses, and event registrations. You can filter your contacts based on any of this activity.

Screenshot of the UbiQuity Database Dashboard showing the Your Database, Your Contacts, and Database Summary sections. — The Database Dashboard showing your database summary, contacts, and key stats.

*** ### Database Fields Fields define the structure of your database. Each field holds a specific type of data for each contact, and UbiQuity uses the field type to validate what gets entered — so an email address field will only accept a valid email address format, for example. You can add and delete fields at any time. The one exception is field type — once a field has been created, its type cannot be changed. If you are unsure what type to use, choose **Text**, which accepts any value up to 500 characters. To manage your fields, go to **Database > Edit Fields**. You will need the appropriate user permissions to make changes here.

#### Field Types

Field Type	Description
Text	Any data, up to 500 characters
Date	Date format, e.g. 20 Oct 2024
Time	Time format, e.g. 23:59
Date/Time	Combined date and time, e.g. 22 Sep 2024, 16:29
Whole Number	Any whole number, e.g. 1, 2, 3. Max value: 2,147,483,647
Decimal Number	A number with decimals, e.g. 2.25
Email Address	Must conform to a valid email address format. Required for sending emails
Mobile Number	Must conform to a New Zealand mobile number (e.g. 0212231234, +642721801234, 027 212 3212) or start with an international country code. Minimum characters required (excluding the prefix) are 6, maximum 9.
Yes/No	True or False
GUID	Unique identifier used for software integration. Set default to Auto for UbiQuity to generate a value automatically
Notes	Any data, up to 500,000 characters. Cannot be searched or filtered
File Upload	Allows multiple file uploads. Enable the Secure option to restrict access to UbiQuity users only

#### System Fields In addition to the fields you create, UbiQuity maintains its own system fields against each contact. You can view these by opening a contact and clicking **View Meta Data**. | System Field | Description | | ------------- | -------------------------------------------------------------------------------- | | ID | A sequential number assigned to each contact | | Reference ID | A unique ID across all of UbiQuity, used to link a contact to all their activity | | Person ID | Used when a contact interacts via social channels | | Create Date | The date and time the contact was created | | Last Modified | The date and time the contact was last updated | | Source | Where the contact originated, e.g. a form, an import | | Version | Incremented each time the contact is updated | | Opted Out | If true, the contact is automatically excluded from Mailouts | | GNA | If true, the contact is automatically excluded from Mailouts. See GNA | #### Field Operations You can do the following with any field in your database: **Create** — Add a new field manually from the Edit Fields screen, or create one during an import. **Edit** — You can update a field's name, description, and default value at any time. You cannot change the field type once it has been set. **Make mandatory** — Contacts cannot be added or imported without a value in a mandatory field. You can set a default value to be used when no value is provided. **Archive** — Archiving hides a field from view throughout UbiQuity but retains all data. Archived fields continue to work in forms and filters where they are already in use. You can unarchive at any time. **Delete** — Deleting a field permanently removes all data within it and cannot be undone. UbiQuity will warn you if the field is in use, but note it cannot detect usage via the API. Consider archiving instead if you are unsure. #### Unique Fields Unique fields help prevent duplicate contacts in your database. UbiQuity strongly recommends setting at least one unique field. For example, if you set Email Address as unique, no two contacts can share the same email address. You can also create unique field combinations. For example, if you set Email Address and First Name together as unique, no two contacts can have the same combination of both values — but they could individually share the same email address or first name.

Screenshot of the bottom of the Database Fields screen showing the Unique Fields section with a rule stating the value of Email Address must be unique, and an Add Unique Group button. — The Unique Fields section showing Email Address set as a unique field.

*** ### Configuring Your Database for Email Before you can send a Mailout, your database needs to be configured for email. This is a one-time setup per account and is usually completed during onboarding. To do this, go to **Database > Configure Database Details**, or navigate to the Email module and follow the prompts. The configuration process sets up the following: * An **Email Address** field (or maps an existing one) * An **Opt Out** field to track unsubscribes * A **GNA** (Gone No Address) field to track hard bounces * Optionally, an Opt Out form that contacts can use to unsubscribe Once configured, UbiQuity will automatically manage opt outs and bounces against these fields. See Opt Outs and GNA for more information on how these work.

Screenshot of the Configure Database for Email dialog overlaid on the Database Details screen, showing dropdowns to select the Opt Out field and Email Address field, and a checkbox to create an associated opt out form. — The Configure Database for Email dialog, where you map your Opt Out and Email Address fields.

*** ### Managing Contacts To view and manage your contacts, go to **Database > View and Edit Contacts**. You can choose which fields are visible in the list, sort by any column, and drag fields to reorder them. Showing only the fields you need will keep the view fast and easy to work with.

Screenshot of the View and Edit Contacts screen in UbiQuity showing the Show/Hide Fields section with checkboxes for each database field. — The View and Edit Contacts screen showing field visibility options.

#### Adding Contacts There are a few ways to add contacts to your database: * **Add Contact** — Use this for adding a small number of contacts one at a time. Click **Add Contact** from the Database dashboard and fill in the fields. * **Forms** — Subscribe or update forms can capture contacts directly from your website or campaigns. * **Import** — The best method for adding or updating a large number of contacts at once. See Importing Contacts for a full guide. * **Connectors** — Set up and manage contacts with automated data transfers between UbiQuity and external systems. * **API** — Contacts can be added and updated programmatically. See API for more information.

Screenshot of the Add Contact screen in UbiQuity showing fields for Email Address, First Name, Last Name, Mobile Number, Suburb, Registration Date, Member, and several connector fields, with Cancel and Add buttons. — The Add Contact screen for manually adding a single contact to your database.

#### Updating Contacts To make the same change across a large number of contacts at once, use **Update Contacts**. Apply a filter to target the contacts you want to change, then select the field and the value to update it to. If you do not apply a filter, all contacts in your database will be updated.

Screenshot of the Update Contacts screen in UbiQuity showing an IF condition filtering contacts where Registration Date equals 7 Dec 2024, and a THEN action to set the Registration Date to 22 Apr 2026. — The Update Contacts screen showing a conditional rule to update the Registration Date field for filtered contacts.

#### Segmenting Contacts Segment Contacts lets you randomly divide your contacts into groups, which is useful for things like subject line testing or send day testing. To segment your contacts: 1. Apply a filter to target the contacts you want to include. If no filter is set, all contacts will be segmented. 2. Select an existing database field to store the segment values, or create a new one. 3. Define your segments by specifying a number or percentage of contacts for each group, and assign a value to identify each segment. 4. Click **Segment Contacts** to apply. You can then filter and personalise based on the segment field.

Screenshot of the Segment Contacts screen in UbiQuity showing an IF condition filtering contacts where Member equals Yes, and an INTO section dividing contacts into three segments of 33 percent each, with different Registration Date field values assigned to each segment. — The Segment Contacts screen showing a filter applied to Member contacts, with three equal segments being assigned different Registration Date values.

#### Deleting Contacts To delete multiple contacts at once, use **Delete Contacts**. Apply a filter to target the contacts you want to remove, then confirm the deletion. A preview of the contacts to be deleted will appear before you confirm. Please note: * Deleting a contact also permanently deletes all of their contact history, including email activity, form submissions, and event registrations. * This action cannot be undone. Double-check your filter before proceeding. #### Downloading Contacts To export your contacts, use the download option from the contacts view. Only the fields currently visible will be included, and if you have a filter active, only the filtered contacts will be downloaded. If your database includes File Upload fields, you can choose to include the uploaded files in a zip download. *** ### Contact History Every contact has a full history of their interactions with UbiQuity. To view it, open a contact and click **Contact History**. This shows all activity for that contact, including emails delivered and read, links clicked, form submissions, survey responses, and event registrations.

Screenshot of the Contact History screen in UbiQuity showing a chronological list of interactions for a contact, including Engage Mail sends with Read and Unread statuses, and Engage Database imports showing Contact updated actions. — The Contact History screen showing a full log of interactions for a single contact.

{% hint style="info" %} **Tip:** If you click the View button next to an email in the contact history, you can see exactly what the email looked like and resend it to the same address or an alternative. {% endhint %} *** ### Transactional Data Transactional data lets you store multiple records against a single contact — useful when there is a one-to-many relationship between a contact and the data you want to capture. Common examples include purchase history, vehicle records, service requests, or phone call logs. Unlike the main database, which holds one row per contact, a transactional database can hold as many records as needed per contact. Each record must be linked to a contact in your main database. You can create as many transactional databases as you need, each with their own fields and structure. To get started, go to **Database > Manage Transactional Data** and click **Create Transactional Database**.

Screenshot of the Transactional Data screen in UbiQuity showing a list of two transactional databases named Purchases and Service Requests, with their created and last modified dates, and a Create Transactional Database button. — The Transactional Data screen showing two existing transactional databases and the ability to create a new transactional database.

#### Adding and Viewing Transactions You can add and view transactions in similar ways to your Contact data: * **Via the contact record** — Open a contact and scroll to the bottom of the page. You will see a section for each transactional database, where you can view existing records and add new ones. * **Via the transactional database view** — Go to **Database > Manage Transactional Data**, select the database, and click **View and Edit Transactions** to see all records across all contacts. For adding a large number of transactions at once, use the import function, Connectors or the API. See [Importing Transactions](/documentation/data-and-integrations/imports/importing-transactions.md) for a full guide.

Screenshot of the bottom of a contact record in UbiQuity showing a Service Requests transaction. — A contact record showing one Service Requests transactional data record.

#### Filtering on Transactional Data When filtering your contacts, you can include conditions based on transactional fields — for example, finding all contacts who purchased a specific product, or whose total spend is above a certain value. See Filtering for more information. *** ### Importing Contacts and transactional data can both be imported from CSV or text files. Full step-by-step guides are available in the Data & Integrations section: * [Importing Contacts](/documentation/data-and-integrations/imports/importing-contacts.md) * [Importing Transactions](/documentation/data-and-integrations/imports/importing-transactions.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ubiquity.co.nz/documentation/audience-management/database.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.