Reference Editor

References are custom data lists that you can use in policy rules. When default verification sources do not cover your use case, create a reference to supply your own data such as allowed domains, blocked email addresses, or custom allowlists and blocklists.

What Are References?

References store raw data lists that policy rules can check against. Examples include:

  • A list of trusted email domains for your organization
  • Email addresses that should always be flagged
  • IP ranges specific to your infrastructure
  • Custom identifiers for your application

Policies reference these lists by their reference key, and the Intelligence API checks incoming data against the items in your references.

Creating a Reference

To create a new reference:

  1. Click the Create Reference button
  2. A modal window appears with the following fields:
FieldDescriptionConstraints
Reference keyA unique identifier for the referencePermanent, cannot be changed after creation. Must match: lowercase letter followed by lowercase letters, numbers, or underscores (regex: /^[a-z](?:[a-z0-9_]*[a-z0-9])?$/)
DescriptionA human-readable description of the reference purposeOptional, can be updated later
Data itemsThe list of values to include in the referenceOne item per line, maximum 10,000 items per reference
  1. Enter each data item on a single line in the text area
  2. Click the Create button

After creation, the reference is immediately available for use in policy rules.

Important

Reference keys are permanent. Choose keys carefully because you cannot rename a reference after creation.

Reference Key Format

Reference keys must follow this format:

  • Must start with a lowercase letter
  • Can contain lowercase letters, numbers, and underscores
  • Must end with a lowercase letter or number
  • Regex pattern: /^[a-z](?:[a-z0-9_]*[a-z0-9])?$/

Examples:

  • allowed_domains - Valid
  • blocked_emails - Valid
  • trusted_ips - Valid
  • Allowed_Domains - Invalid (uppercase)
  • _blocked - Invalid (cannot start with underscore)
  • 1trusted - Invalid (cannot start with number)

Data Item Formatting

  • Enter one item per line
  • Any data type is allowed (strings, numbers, etc.)
  • Empty lines are automatically ignored
  • The system automatically trims leading and trailing whitespace from each line
  • Duplicate items are automatically deduplicated. Only a single instance is stored.

Updating a Reference

To modify an existing reference:

  1. Locate the reference in the Reference Editor list
  2. Click the Update button for that reference
  3. Modify the description or the data items as needed
  4. Save your changes

Changes take effect immediately in any policy rules that reference this data.

Important

Changes to references take effect immediately in all policies that use them.

When to Update References

Update references when:

  • You need to add new items to an allowlist or blocklist
  • You want to remove items that are no longer relevant
  • You need to correct errors in the data

Deleting a Reference

To delete a reference:

  1. Locate the reference in the Reference Editor list
  2. Click the Delete button for that reference
  3. Confirm the deletion

Grace Period for Deleted References

When you delete a reference:

  • The reference continues to work in policies for 7 days
  • During this grace period, you must remove the reference from any policies that use it
  • After 7 days, the reference data is permanently removed
  • Policies that still reference the deleted key will fail

Warning

Remove the reference from all policies before the 7-day grace period expires to prevent API failures.

Performance Recommendations

Tip

For optimal performance, keep references under 100 items when possible. Larger references may impact verification request latency.

The maximum limit is 10,000 items per reference.

Using References in Policies

To use a reference in a policy:

  1. Create the reference and note its reference key
  2. Open the Policy Editor
  3. Use the reference key in your policy configuration
  4. Save the policy

The specific syntax for referencing custom data depends on the policy rule type. See the Policy Structure documentation for details.