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

# New User Registration

> Guide a new contact through portal self-registration, matching or creating their Account and blocking duplicates.

## Overview

The **New User Registration** accelerator (FS New User Registration) replaces the stock Experience Cloud self-registration form with a guided flow built for associations. A prospective member enters their email; the accelerator checks it against existing Users, a banned-domain list, and optionally existing Contacts, before letting them search for and join an existing Account, get auto-matched by email domain, or create a new one — depending on how you configure it. The goal is to onboard portal users without creating duplicate Contacts or Accounts.

This accelerator requires the [fusionSpan Common Base Library](/end-user-guides/accelerators/fusionspan-common-base-library) as a documented install prerequisite, and is not part of core fusionCore.

<Note>
  Despite "Fonteva" appearing in this package's internal repository name, it runs on base Salesforce with no Fonteva dependency — it also has optional support for orgs that do have Fonteva or Nonprofit Success Pack installed.
</Note>

## Prerequisites

* Install the fusionSpan Common Base Library first.
* Decide which registration model you want: **Domain Matching** (auto-affiliate by email domain) or **Account Search** (let the user search for and pick their organization) — you can only enable one. If using Account Search, also decide between a results table or type-ahead search.
* If using reCAPTCHA (on by default), a Google reCAPTCHA site key and secret.

## How to Configure

<Steps>
  <Step title="Create the settings record">
    Create a `FS_New_User_Reg_Settings__mdt` record. At minimum, set `FS_Admin_Id__c` to a User Id that should own Accounts created or claimed during registration — registration silently fails without this.

    <Frame caption="A configured settings record — Admin Id is the field most setups miss">
      <img src="https://mintcdn.com/fusionspan/EW_gg4_8FJ-921wF/images/end-user-guides/442663483/nur_settings_detail.png?fit=max&auto=format&n=EW_gg4_8FJ-921wF&q=85&s=9e2e1735b9e1cb5e1fd79af4e01fff97" alt="An FS New User Reg Settings record with the Admin Id field highlighted in a red box, alongside Verify Email Field, Enable reCaptcha, Contact Email Match, and Create Contact Field Set" width="1280" height="400" data-path="images/end-user-guides/442663483/nur_settings_detail.png" />
    </Frame>
  </Step>

  <Step title="Configure banned domains and account matching">
    Set `FS_Banned_Email_Domains__c` to a comma-separated list of domains to block (enter them in lowercase — matching is case-sensitive). If using Domain Matching, populate `Account.FS_Email_Domain__c` on the Accounts you want matched by email domain.
  </Step>

  <Step title="Choose what happens when no match is found">
    Configure `FS_Allow_Account_Creation__c` (let the user create a new Account), `FS_Save_Without_Account__c` (let them register without one), and/or `FS_Self_Registration_Bucket_Account__c` (a catch-all Account for otherwise-unmatched registrants). These options are mutually exclusive in several combinations — the settings record blocks invalid combinations when you save it.
  </Step>

  <Step title="(Optional) Configure reCAPTCHA">
    Create a `FS_Google_reCAPTCHA_Configuration__mdt` record with your site and secret keys. reCAPTCHA is on by default — if this record is missing, verification fails and blocks registration.
  </Step>

  <Step title="Assign permission sets">
    Assign **New User Registration Admin** to admins, and **New User Registration Portal** to the community's guest/portal profile.
  </Step>

  <Step title="Add the component to your registration page">
    In Experience Builder, add the **FS New User Reg** Lightning web component to your registration page, and set its `customMetadataSettingName` design property to the label of the settings record you created above.
  </Step>
</Steps>

## Limitations and Common Pitfalls

* **A blank Admin Id silently stops registration.** If `FS_Admin_Id__c` is empty, the flow fails without a clear message to the end user — this is the most common setup mistake.
* **Banned-domain matching is a substring check, not an exact match.** Enter domains in lowercase, and be aware that a banned domain that's a substring of another domain (for example, banning `mygmail.com`) can unintentionally also block a shorter domain like `gmail.com`.
* **Domain matching requires the domain field to be populated and to match exactly** (aside from whitespace) — a typo or unpopulated `FS_Email_Domain__c` means that Account is never suggested.
* **reCAPTCHA defaults to on even if you never explicitly enabled it.** If the reCAPTCHA settings record or keys are missing, the "Verify Email" step fails for every visitor — either configure reCAPTCHA or explicitly turn it off.
* **The username-already-exists check can't be turned off.** Registration always checks for an existing `User` with that email as the username.
* **Missing field sets cause a hard error.** If a field set you referenced in the settings record was never deployed to this org, registration errors out — confirm every configured field set actually exists before going live.
* **For Person Account orgs**, make sure the email field and field sets you reference point to Account fields (for example `PersonEmail`), not Contact fields — the settings record's help text calls this out, but it's an easy mistake to copy from a non-Person-Account org.