[JCC] - Add 'previousSSN' field to license upload process for correcting incorrect SSN uploads

backend/compact-connect/docs/README.md

@@ -62,6 +62,7 @@ leave the field entirely empty. If some of your licenses are missing a required
 | middleName | Provider's middle name (optional) | String (max 100 chars) | Robert |
 | npi | National Provider Identifier (optional) | 10-digit number | 1234567890 |
 | phoneNumber | Provider's phone number (optional) | [ITU-T E.164 format](https://www.itu.int/rec/T-REC-E.164-201011-I/en) (must include country code, no spaces or dashes) | +12025550123 |
+| previousSSN | The incorrect Social Security Number previously uploaded for this license (optional). Provide this along with the corrected `ssn` to fix a license record that was uploaded with the wrong SSN: the system moves the license record and any privileges purchased against it over to the provider associated with the corrected SSN. If the corrected license was the only license under the incorrect SSN, that duplicate provider account is removed and the practitioner is emailed to register again. | Format: XXX-XX-XXXX | 123-45-6789 |
 | suffix | Provider's name suffix (optional) | String (max 100 chars) | Jr. |
 ** This field is required by compact commission rule, however, to avoid making a breaking change for states that are already integrated, the API does not enforce this rule. States are responsible for enforcing the compact rule themselves.
 #### Example CSV
@@ -107,7 +108,13 @@ If data is not available for a required field, that particular license record ca
 
 ### Can we upload the same licenses multiple times? What if their information changes?
 
-Yes. CompactConnect is designed to automatically detect and track changes to license records over time. When you upload a license record, CompactConnect will determine if the record currently exists in the CompactConnect database using the provided SSN to match with any existing licensee in the system, and create the record if not found. If the license record already exists, CompactConnect will check the differences between the existing record in the system and changes uploaded by the state, and apply the changes accordingly.
+Yes. CompactConnect is designed to automatically detect and track changes to license records over time. The Social Security Number (SSN) is the unique identifier CompactConnect uses to create and match individual practitioner accounts. When you upload a license record, CompactConnect uses the provided SSN to determine whether that practitioner already has an account in the system, creating one if not found. If the practitioner's account already exists, CompactConnect will check the differences between the existing license record and the changes uploaded by the state, and apply the changes accordingly.
+
+Because accounts are matched on SSN, simply changing the SSN in your state's system and then uploading the corrected license will **not** update the practitioner's existing CompactConnect account. It will create a brand new, separate account under the new SSN and leave the original account (and any privileges tied to it) unchanged. If a license was previously uploaded with an incorrect SSN, use the `previousSSN` field (see the field table above) when uploading the corrected SSN so CompactConnect can migrate the practitioner's existing account instead of creating a duplicate.
+
+> **⚠️ Verify SSNs before you upload.** The SSN is the sole identifier CompactConnect uses to match a license to a practitioner's account, and every downstream consequence of an upload (account creation, privilege eligibility, public lookup, etc.) follows from it. Uploading an incorrect SSN is not a low-risk mistake to leave unaddressed, as it silently creates or attaches records to the wrong account, fragmenting the practitioner's licensure history and leaving privileges tied to whichever account was in place at the time they were purchased.
+>
+> Correcting an SSN with `previousSSN` is itself a significant action which migrates (moves) the affected license and any privileges purchased against it to the account associated with the corrected SSN and forces the practitioner to re-register if they have already registered under the account with the incorrect SSN. Because of this, during onboarding testing before a state begins uploading licenses into the production account, it is imperative that the state verify there is no issue with the internal process or data pipeline that sends licensure data to CompactConnect which could result in incorrect or inconsistent SSNs being uploaded, so that this feature is not relied upon to routinely correct otherwise avoidable upload errors.
 
 ### Which of these license values will be publicly visible?