Skip to main content
A jurisdiction is the top-level organizational unit in Bloom Housing. It represents a city, county, housing authority, or other governmental body that administers affordable housing listings within a Bloom installation. A single Bloom deployment can serve multiple jurisdictions simultaneously, each with its own configuration, feature flags, email settings, and supported languages.

​
What a jurisdiction contains

The Jurisdiction DTO (jurisdiction.dto.ts) defines the full set of per-jurisdiction configuration:
  • name — the jurisdiction’s display name (required, max 256 characters)
  • publicUrl — the base URL of this jurisdiction’s public-facing portal
  • emailFromAddress — the sender address used for all outgoing emails from this jurisdiction
  • notificationsSignUpUrl — optional link to a notifications sign-up page (e.g., GovDelivery)
Each jurisdiction specifies which languages it supports via the languages array (LanguagesEnum values, e.g., en, es, zh, vi, tl). The TranslationService uses this to serve the correct locale for public portal content. Translations can be defined generically (shared across jurisdictions) or overridden per-jurisdiction.
The featureFlags array holds FeatureFlag records linked to the jurisdiction. Each flag has a name (matching FeatureFlagEnum) and an active boolean. Features that are absent from the array default to their off state. Feature flag evaluation is performed by doJurisdictionHaveFeatureFlagSet() at runtime.
  • requiredListingFields — list of field names that must be filled before a listing can be published
  • minimumListingPublishImagesRequired — minimum number of images required to publish
  • listingApprovalPermissions — UserRoleEnum array defining which roles can approve listings
  • duplicateListingPermissions — UserRoleEnum array defining which roles can duplicate listings
  • listingFeaturesConfiguration — structured configuration of which listing feature sections are visible
  • visibleNeighborhoodAmenities — which NeighborhoodAmenitiesEnum values are shown in listings
  • visibleAccessibilityPriorityTypes — which accessibility priority types are shown on applications
  • visibleSpokenLanguages — which spoken language options appear in demographics (requires enableSpokenLanguage flag)
  • raceEthnicityConfiguration — structured configuration for race/ethnicity question options
  • allowSingleUseCodeLogin — when true, allows login via single-use code (magic link) for this jurisdiction
  • enableGeocodingPreferences — enables address geocoding for preference verification (also a direct boolean field on the DTO, mirroring the feature flag)
  • enableGeocodingRadiusMethod — enables radius-based geocoding for preference verification
  • enablePartnerDemographics — includes demographics in partner exports
  • enablePartnerSettings — shows the Settings tab in the Partners Portal
  • rentalAssistanceDefault — default rental assistance text shown on listings
  • whatToExpect — default “what to expect” body text shown on listings
  • whatToExpectAdditionalText — extended “what to expect” text (requires enableWhatToExpectAdditionalField flag)
  • whatToExpectUnderConstruction — text shown for listings that are under construction
  • referralSummaryDefault — default summary text for referral-type application methods
  • partnerTerms — terms and conditions text presented to partners on sign-up
  • regions — list of configurable region names available for listings
multiselectQuestions links the jurisdiction to the set of preferences and programs available for listing configuration. These are referenced by ID and resolve to full MultiselectQuestion records at query time.

​
Multi-jurisdiction support

A single Bloom installation can serve multiple jurisdictions from one database and one API. Each listing, application, and user account is associated with a specific jurisdiction. When a request arrives, the API resolves the relevant jurisdiction through:
  • The jurisdictionId on the listing or application being accessed
  • The jurisdiction filter on listing queries
  • The jurisdictionName or jurisdictionId path parameter on jurisdiction-specific endpoints
This design allows housing authorities that serve multiple localities (e.g., a county with several cities) to manage all their listings from a single platform while maintaining separate configurations, branding, and feature sets per jurisdiction.

​
Feature flags

Feature flags are the primary mechanism for enabling or disabling functionality per jurisdiction. They are stored as FeatureFlag records and evaluated at runtime.
The FeatureFlagEnum in feature-flags-enum.ts is a reference list to keep backend and frontend in sync. Flags are stored as strings in the database, so new flags can be added without schema migrations.
Selected feature flags and their effects:
FlagEffect
enableSingleUseCodeAllows login to this jurisdiction using single-use code (magic link) flow
disableJurisdictionalAdminPrevents jurisdictional admin accounts from being created
enableSupportAdminAllows support admin accounts to be created
FlagEffect
disableCommonApplicationRemoves the digital Common Application as an option for listings
disableBuildingSelectionCriteriaHides building selection criteria from listings
disableListingPreferencesRemoves the preferences section from listings
enableGeocodingPreferencesEnables geocoding-based verification for listing preferences
enableGeocodingRadiusMethodEnables radius-based geocoding for preference eligibility
enableHomeTypeEnables the home type field on listings
enableIsVerifiedAllows listings to be manually verified
enableMarketingStatusShows marketing status section (coming soon) in listing form
enableNonRegulatedListingsEnables non-regulated listing type
enablePropertiesEnables the properties feature for grouping listings
enableRegionsEnables region assignment for listings
enableUnitGroupsUses unit groups instead of individual units on listings
enableListingFavoritingShows a Favorite button on public listing cards
enableListingOpportunitySends a GovDelivery email alert when new listings are published
enableSection8QuestionShows Section 8 acceptance data on listings
hideCloseListingButtonHides the manual close button in the listing edit form
FlagEffect
disableEthnicityQuestionHides the ethnicity question from application demographics
disableWorkInRegionRemoves the “Work in Region” question from applications
enableApplicationStatusEnables applicant-facing application status tracking
enableFullTimeStudentQuestionShows the full-time student question on applications
enablePartnerDemographicsIncludes demographic data in partner exports
enableVerifyIncomeValidates reported income against AMI limits on submission
enableSpokenLanguageShows a spoken language question in application demographics
enablePartnerSettingsShows the Settings tab in the Partners Portal
FlagEffect
enableWaitlistLotteryEnables lotteries for waitlist-type listings
enableWaitlistAdditionalFieldsShows additional fields in the waitlist section of the listing form
enableV2MSQActivates the new multiselect question logic for lottery preference ranking

​
Creating and managing jurisdictions

Jurisdictions are managed by system administrators. The Partners Portal exposes jurisdiction management for admin-level users.
1

Create a jurisdiction

Send a POST /jurisdictions request with a JurisdictionCreate payload. Required fields include name, publicUrl, emailFromAddress, languages, whatToExpect, whatToExpectAdditionalText, whatToExpectUnderConstruction, rentalAssistanceDefault, listingApprovalPermissions, duplicateListingPermissions, multiselectQuestions, requiredListingFields, regions, visibleNeighborhoodAmenities, visibleAccessibilityPriorityTypes, and visibleSpokenLanguages.
2

Configure feature flags

After creation, add FeatureFlag records linked to the jurisdiction to enable or disable platform features. Feature flags can be managed via the jurisdiction update endpoint.
3

Set up translations

Configure the languages array on the jurisdiction to match the locales you want to support. Add translation records for any jurisdiction-specific content overrides.
4

Invite jurisdictional admins

Create user accounts with the jurisdictionalAdmin role scoped to the jurisdiction. These users can manage listings, applications, and partners within their jurisdiction but cannot access other jurisdictions’ data.

​
Jurisdiction service internals

The JurisdictionService (jurisdiction.service.ts) always fetches jurisdiction records with the featureFlags and multiselectQuestions relations included. Lookups can be performed by either jurisdictionId (UUID) or jurisdictionName (string). The service throws a NotFoundException if no matching jurisdiction is found and a BadRequestException if neither identifier is provided.

​
API endpoints

MethodPathDescription
GET/jurisdictionsList all jurisdictions (includes feature flags and multiselect questions)
GET/jurisdictions/:jurisdictionIdGet a jurisdiction by UUID
GET/jurisdictions/byName/:jurisdictionNameGet a jurisdiction by name
POST/jurisdictionsCreate a new jurisdiction
PUT/jurisdictions/:jurisdictionIdUpdate a jurisdiction by UUID
DELETE/jurisdictionsDelete a jurisdiction by ID (passed in request body)
Deleting a jurisdiction will affect all listings, applications, and users associated with it. This operation is protected by API key and admin-level permission guards. Use with caution in production.
To check whether a specific feature flag is active for a jurisdiction at runtime, use the doJurisdictionHaveFeatureFlagSet(jurisdiction, FeatureFlagEnum.flagName) utility function from feature-flag-utilities.ts.

Build docs developers (and LLMs) love

Get started for freeTalk to us