Applicant Referencing

The applicant referencing workflow lets agents initiate tenant reference checks directly from an offer detail page using the Blinc-UK integration. References can be submitted one applicant at a time or for all applicants on an offer in a single bulk action.

Prerequisites

• Blinc-UK must be configured for your organisation. If it is not, a warning banner is shown in the referencing section and submissions will be blocked.
• The offer must have at least one applicant attached.

Accessing the Referencing Section

Open any offer from the Offers dashboard. The Applicant Referencing section is displayed below the main offer details. Each applicant on the offer is listed with their current reference status.

Referencing a Single Applicant

1. Locate the applicant row in the referencing section.
2. Click the three-dot (⋯) menu on the right-hand side of the row.
3. Select Reference Applicant.
   • If a reference is already active for this applicant, the menu item will show "Reference in Progress" and will be disabled.
4. In the modal that opens:
   • Choose a Reference Type: Standard, Enhanced, or Comprehensive.
   • Optionally check Include Digital Identity Check.
5. Click Submit Reference.

The applicant row will update to show the reference status in real time.

Referencing All Applicants (Bulk Action)

1. Click Reference All in the section header.
2. In the bulk reference modal:
   • Choose a Reference Type to apply to all applicants.
   • Optionally check Include Digital Identity Check.
3. Click Submit References.

After submission a results summary is shown:

Result	Meaning
Submitted	Reference was successfully sent to Blinc-UK.
Skipped	Applicant already has an active reference; not re-submitted.
Failed	Submission failed for this applicant (see error detail).

Reference Status Badges

Each applicant row displays a status badge that updates as the reference progresses:

Status	Description
Pending	Submitted, awaiting Blinc-UK to begin processing.
In Progress	Blinc-UK is actively running the reference check.
Completed	Reference check finished.
Failed	Reference check encountered an error.
Cancelled	Reference was cancelled.

Once completed, an outcome badge is also shown:

Outcome	Description
Passed	Applicant passed the reference check.
Referred	Applicant's reference requires further review.
Failed	Applicant did not pass the reference check.

If a Digital Identity Check was requested, an indicator is shown alongside the status badges.

Refreshing Statuses

Click the Refresh button in the section header to pull the latest status for all in-progress references. This is useful when you want to check for updates without reloading the full page.

Duplicate Prevention

The system automatically prevents duplicate submissions:

• Single reference: If an applicant already has an active reference, the menu action is disabled.
• Bulk reference: Applicants with an existing active reference are silently skipped and counted in the "Skipped" total.

Audit Trail

All referencing actions are recorded in the audit log:

Event	Trigger
applicant_submitted	A reference is submitted for a single applicant.
bulk_offer_submitted	A bulk reference submission is made for an offer.

Each audit entry includes full metadata such as the applicant ID, offer ID, reference type, and identity check flag.

API Reference (tRPC)

The following procedures are available under the referencing router:

referencing.submitForApplicant

Submits a reference for a single applicant.

Input

{
  applicantId: string;          // ID of the applicant to reference
  referenceType: "standard" | "enhanced" | "comprehensive";
  identityCheckRequested: boolean;
}

Behaviour

• Auto-populates applicant name, email, phone, and offer property address from existing records.
• Returns an error if the applicant already has an active reference.

---

referencing.bulkSubmitForOffer

Submits references for all applicants on a given offer.

Input

{
  offerId: string;
  referenceType: "standard" | "enhanced" | "comprehensive";
  identityCheckRequested: boolean;
}

Response

{
  results: Array<{
    applicantId: string;
    status: "in_progress" | "failed";
    skipped: boolean;
    error?: string;
  }>;
}

---

referencing.listByApplicant

Returns the full reference history for a specific applicant.

Input

{ applicantId: string }

---

referencing.listByOffer

Returns reference statuses for all applicants on an offer.

Input

{ offerId: string }

Response includes a byApplicant map keyed by applicant ID for efficient UI rendering.