How do I set up deduplication using a partial SSN?

Last updated: November 2, 2026

Match returning candidates on the last few digits of their SSN, so someone who registers with a new email still lands on their existing record instead of creating a duplicate.

Before you start

  • Access to Account Settings and Custom Attributes

  • A registration form you can edit, and permission to create registration links

Steps

The setup has four phases. You create a custom attribute to hold the partial SSN, point duplicate detection at it, update the registration form, then create the registration link. Keep this order. When you create a link, Onboarded checks that its form collects SSN, so the settings have to exist first.

Create the custom attribute

  1. Go to Organization Settings → Custom Attributes and create a new custom attribute.

  2. Set Entity to Employee and Scalar Type to String. The name, entity and scalar type can't be changed after you create the attribute.

  3. Give it a name, for example last_6_ssn. Its path will be employee.custom_attributes.last_6_ssn.

Point duplicate detection at it

  1. Go to Account Settings → Edit Account and find Employee Duplicate Detection (Registration Link).

  2. In Match Criteria, select SSN. Two more fields appear.

  3. In SSN Digits to Match, enter the number of trailing digits to compare, from 4 to 9. For example, enter 6.

  4. In Partial SSN Custom Property, pick the attribute you created in step 3.

  5. (Optional) To match the way TempWorks does, also select Last name in Match Criteria. A candidate then counts as a duplicate only when the SSN digits and the last name both match. Letter case and extra spaces don't matter.

  6. Select Update Account.

The digit count and the property are one setting, so fill in both or clear both. If you pick a property that isn't a String, the form won't save. Last name can't be your only criterion: on its own, the form won't save.

Every selected criterion has to match.

If Match Criteria includes both Email and SSN, a candidate only counts as a duplicate when their email and SSN both match an existing record. A returning candidate with a new email won't be caught. To catch that case, select SSN on its own.

Update the registration form

  1. Open your registration form in Form Studio.

  2. Change the SSN field's path to the new attribute (employee.custom_attributes.last_6_ssn) so it no longer writes to employee.social_security_number.

  3. Tell candidates how many digits to enter, for example "Last 6 digits of your SSN."

  4. Deploy the new version.

Verify

  1. Open the job board and register a test candidate with a new email and partial SSN 456789.

    The candidate is created.

  2. Open the link again. Use a different email and the same 456789, then continue.

    You land on Profile Found, which says Onboarded found a profile associated with "your Social Security Number."

  3. Select Yes, that's me.

    A one-time code goes to the email or phone number on the existing record. Once the candidate enters it, they continue as that candidate and no duplicate is created.

Candidates who already have a full SSN on file

Partial matching also works against full SSNs already stored in employee.social_security_number. Onboarded strips dashes before comparing. Take a candidate created in the dashboard with SSN 123-45-6789. If they register with a new email and enter 456789, Onboarded matches them to that record.

If a candidate has a full SSN on file, the full SSN is what gets compared. Any partial value saved to their custom attribute is ignored.

If it doesn't match

  • The candidate entered fewer digits than SSN Digits to Match. Onboarded falls back to an exact full-SSN comparison, which a partial value never passes. Entering more digits is fine: only the trailing ones are compared.

  • Email or Phone is also selected. Every selected criterion has to match (see the warning above).

  • The form field still writes to the old path, or the link still uses the old form.

  • The existing record has no email or phone. The candidate sees a support message instead of a code, because there's nowhere to send one.

Duplicate detection only runs on registration links. Candidates created in the dashboard or through the API aren't checked.