A retrieval is when a returning client is added to a new case using their existing profile, rather than being added as new. Retrieving clients every time they return keeps their verification history, ongoing monitoring and CDD refresh dates on one record.
Saving and reusing profile IDs
- When you first create a case, request
profileIdon each of the case’sentitiesandindividuals. Save these against the client in your own system. - When the client comes back, pass the saved
profileIdintoexistingRootEntityorexistingIndividualsoncreateCase, orexistingIndividualsonaddExistingIndividualsToCase, rather than adding them as new. See create a case from existing profiles. - The new case pulls in the existing profile and its verification history, and no duplicate is created.
No profileId stored yet? Search for the profile with searchIndividualProfiles or searchEntityProfiles first to find the existing record. If a saved profileId belongs to a profile that has since been merged, retrieval picks up the winning profile, and the INDIVIDUAL_PROFILES_MERGED and ENTITY_PROFILES_MERGED webhook events tell you when to update the ID you have stored. See merged profiles.
Verification on returning clients
Verification requirements depend on what you retrieve:
- An existing entity keeps its completed requirements.
- An existing individual retrieved on their own has their requirements reopened.
- New entities and individuals follow the normal verification requirements.
Reopening requirements does not itself run verification checks. To request eligible checks at case creation, set runVerificationChecks: RUN_ALL on createCase (the default is DO_NOT_RUN), or call the runVerificationChecks mutation afterwards to queue eligible checks for individuals on the case. Checks require sufficient data, and the separate mutation skips checks that have already run when their required data is unchanged.
Separately, needsVerification on a new individual controls whether they are checked at all: true sets them to In Progress, false to Not Needed.
How CDD refresh works
Each client’s refresh due date comes from their last verified date and the review period for their risk level. A Compliance Admin turns CDD refresh on per risk level under Settings › Ongoing.
The risk level is the one on the client’s profile, set by the Client Risk Assessment completed on the case, not the case (matter) risk assessment. A client with no risk level may be scheduled under the Default alert period. Retrieving returning clients keeps one schedule per client.
Only a real reverification moves the date:
- Passing the client in a case tagged CDD Refresh
- Selecting Update last verified date in a normal case
A client’s schedule starts the first time they are passed as the root individual or entity in any case, including one created through the API. After that, normal cases and screening checks leave the date alone.
CDD refresh alerts, due dates and refresh cases are managed in the First AML platform for now. Refresh status and refresh webhooks are not yet available through the API. For the platform steps, see the CDD refresh alerts article in the First AML help centre.
Migrating existing clients
Migrating clients through the API? Include each entity and individual’s last verified date in lastVerifiedOn on EntityDetailsInput or IndividualDetailsInput when you create the case. Their refresh schedule starts from that date, so they keep their existing review cycle instead of all falling due on migration day.
lastVerifiedOn only applies when the case creates a new profile. If the profile already has CDD refresh dates, the value is ignored.
Checklist
- Request and store the
profileIdfor every entity and individual. - Retrieve returning clients by their stored
profileId. - Search profiles when no
profileIdis stored. - Subscribe to the profile merged webhook events and update stored profile IDs when a merge comes through.
- Set
lastVerifiedOnfor migrated clients. - Complete a Client Risk Assessment on each case so clients are refreshed on the right cycle.
- Turn on CDD refresh for the right risk levels under Settings › Ongoing.
- Deactivate a profile when a relationship ends, to pause refresh and monitoring.