Application sections
An application (Application DTO, application.dto.ts) collects data across several sections:
Applicant
Primary applicant name, date of birth, email, phone number, work-in-region flag, full-time student status, home address, and work address.
Household members
Additional people in the household. Each member has a name, date of birth, relationship to the primary applicant, home and work addresses, and a same-address flag. Supported relationships (
HouseholdMemberRelationship): spouse, registeredDomesticPartner, parent, child, sibling, cousin, aunt, uncle, nephew, niece, grandparent, greatGrandparent, inLaw, friend, aideOrAttendant, other.Demographics
Optional self-reported demographic data including race, ethnicity, gender, sexual orientation, and how the applicant heard about the listing. Collected to meet fair housing reporting obligations. The
disableEthnicityQuestion feature flag can suppress the ethnicity question per jurisdiction.Preferences
Multiselect questions that correspond to listing preferences (e.g., Live/Work in the City, Displaced Tenant). Applicant responses are stored in
applicationSelections and linked to MultiselectQuestion records via applicationMultiselectQuestions. Preference responses can trigger geocoding validation when enableGeocodingPreferences is enabled.Income
Reported household income amount and period (
monthly or annual per IncomePeriodEnum). The enableVerifyIncome feature flag enables server-side validation of reported income against AMI limits for the listing’s units.Alternate contact
An optional secondary contact who can receive application-related communications on behalf of the applicant. Relationship types (
AlternateContactRelationship): familyMember, friend, caseManager, other, noContact.Accessibility
Optional accessibility needs for the unit:
hearing, mobility, vision, other (boolean flags).Addresses
Home address, mailing address (if different), and alternate address. Each address includes street, city, county, state, zip, and optional latitude/longitude for geocoding.
Application statuses
TheApplicationStatusEnum (from @prisma/client) defines valid submission states:
| Status | Description |
|---|---|
draft | Applicant has started but not yet submitted the application |
submitted | Application has been formally submitted |
removed | Application has been withdrawn or removed |
ApplicationReviewStatusEnum tracks partner review state:
| Status | Description |
|---|---|
valid | Application is eligible and ready for review |
duplicate | Application has been marked as a duplicate |
pendingVerification | Application is awaiting verification |
markedAsDuplicate boolean flag that is set by the flagged set resolution workflow.
Flagged sets (duplicate detection)
When multiple applications appear to share the same household (matching name, date of birth, or address combinations), Bloom creates an Application Flagged Set (AFS). TheafsLastRunAt field on the listing records when this process last ran.
Flagged sets allow partners to:
- Review potentially duplicate applications side-by-side
- Mark one application as the canonical record
- Mark others as
markedAsDuplicate: true, which excludes them from the lottery
Duplicate detection runs automatically as part of the listing close process. Applications marked as duplicates are excluded from lottery randomization.
Submission paths
- Applicant submission (public portal)
- Partner hand-entry
Housing seekers use
POST /applications/submit to submit their application. This endpoint:- Requires validation groups
defaultandapplicants - Sends a confirmation email via
EmailService - Associates the application with the authenticated user’s account if signed in
- Runs geocoding if
enableGeocodingPreferencesis active on the listing’s jurisdiction
POST /applications/verify to pre-validate an application payload without saving it.Partners portal workflow
View applications
Navigate to a listing in the Partners Portal and open the Applications tab. The list view uses the
partnerList application view, which includes applicant name, DOB, contact info, address, and submission metadata.Review flagged sets
Open the Flagged tab to review duplicate application sets. Resolve each flagged set by selecting which application to retain.
Edit an application
Partners can update an application via
PUT /applications/:id. Use POST /applications/:id/notify-update to send the applicant an email notification about the change.Public portal: application status
When theenableApplicationStatus feature flag is enabled on a jurisdiction, applicants can view the status of their submitted applications from their account page. The GET /applications/publicAppsView endpoint returns a summary of an applicant’s applications (grouped by listing) suitable for display on the public portal.
The GET /applications/mostRecentlyCreated endpoint returns the most recently submitted application for the authenticated user, filtered by listing ID.
API endpoints
| Method | Path | Description |
|---|---|---|
GET | /applications | Get a paginated set of applications (ApplicationQueryParams) |
GET | /applications/:applicationId | Get a single application by UUID |
GET | /applications/mostRecentlyCreated | Get the most recent application for the current user |
GET | /applications/publicAppsView | Get public application status summary for the current user |
POST | /applications | Create an application (partner hand-entry) |
POST | /applications/submit | Submit an application (applicant flow) |
POST | /applications/verify | Validate an application payload without saving |
PUT | /applications/:id | Update an application by UUID |
POST | /applications/:id/notify-update | Send applicant an update notification email |
DELETE | /applications | Delete an application by ID (passed in request body) |
PUT | /applications/removePIICronJob | Manually trigger the PII removal cron job |
CSV and spreadsheet export
Applications can be exported in two formats:| Endpoint | Format | Description |
|---|---|---|
GET /applications/csv | ZIP of CSV files | Standard application export |
GET /applications/spreadsheet | ZIP (spreadsheet format) | Formatted spreadsheet export |
GET /applications/csvSecure | Signed URL | Secure CSV download link |
GET /applications/spreadsheetSecure | Signed URL | Secure spreadsheet download link |
ApplicationCsvQueryParams and require partner-level permissions.
PII deletion (data expiry)
Bloom includes a scheduled cron job that removes personally identifiable information from applications older than a configured threshold. This is controlled by theAPPLICATION_DAYS_TILL_EXPIRY environment variable.
When the cron runs, it calls removePII() for each eligible application, which nulls out the following fields:
- Applicant:
firstName,lastName,middleName,birthDay,birthMonth,birthYear,emailAddress,phoneNumber - Household member names, dates of birth, and contact information
- Alternate contact details
- All associated address records (applicant home, work, mailing, alternate)
wasPIICleared flag is set to true on the application record after deletion.
The job can also be triggered manually by calling PUT /applications/removePIICronJob.