> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.fortresstech.io/api-reference/screenings/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.fortresstech.io/_mcp/server. # Screening Overview > Overview of the Screenings API endpoints and functionality > **Note** > > All new integrations using the Screening API require an additional onboarding process. Please contact our team to begin the onboarding process for screening integration. Use the Screening API to retrieve screening requests, view their details, submit results, and update results as new data comes in. ## Key Concepts ### Screening Information Using a given API key, external screening providers can: * **Retrieve screening requests**: Get a list of screening requests that are ready to process * **Access detailed screening data**: Pull comprehensive information for each request, including rent amounts, applicant details, and other screening data * **Submit completed results**: Upload finished screening results back to Fortress once processing is complete * **Update results incrementally**: Patch an existing result to update the overall status, notes, report, or individual method details as data becomes available ### Screening Methods Each property has one or more configured screening methods (e.g., credit check, criminal background check, eviction history). When submitting screening results: * You must provide results for **all** screening methods configured for the property * Each screening method result includes: * `screeningMethodId`: The ID of the screening method * `status`: The result status (APPROVED, DECLINED, PENDING, etc.) * `notes`: Optional notes about the screening method result * The number of screening methods in your request must match the number of methods associated with the screening request ## Integration Flow The typical integration flow for screening providers follows these steps: ```mermaid sequenceDiagram participant Provider as Screening Provider participant API as Fortress API participant UI as Fortress UI Note over Provider,UI: Step 1: Retrieve Pending Requests Provider->>API: GET /screening-requests?status=IN_PROGRESS API-->>Provider: Array of pending requests Note over Provider,UI: Step 2: Get Detailed Information Provider->>API: GET /screening-requests/{id} API-->>Provider: Complete screening details + methods Note over Provider,UI: Step 3: Process Screening Note over Provider: Perform credit check, criminal background,
eviction history, etc. Note over Provider,UI: Step 4: Submit Results Provider->>API: POST /screening-results
(with all screening method results) API-->>Provider: Success confirmation API->>UI: Update screening status Note over UI: Results visible to property managers Note over Provider,UI: Step 5: Update Results (optional) Provider->>API: PATCH /screening-results
(update status, notes, or individual method details) API-->>Provider: Success confirmation API->>UI: Updated results visible Note over UI: Automations re-triggered with updated data ``` ### Step 1: Retrieve Pending Screening Requests First, retrieve the list of screening requests assigned to your organization. Filter for requests with `IN_PROGRESS` status to get only the requests ready for processing: ```bash curl --location 'https://api.fortresstech.io/v1/screening-requests?status=IN_PROGRESS' \ --header 'x-api-key: YOUR_API_KEY' ``` This returns an array of pending screening requests: ```json [ { "id": "6e46a1d7-503a-42fa-a55b-047ee04b5279", "propertyId": "123e4567-e89b-12d3-a456-426614174000", "idempotencyId": "abc123", "status": "IN_PROGRESS" } ] ``` ### Step 2: Get Detailed Screening Information For each pending request, retrieve the complete screening details including customer and household information: ```bash curl --location 'https://api.fortresstech.io/v1/screening-requests/6e46a1d7-503a-42fa-a55b-047ee04b5279' \ --header 'x-api-key: YOUR_API_KEY' ``` This provides all customer/household-related data necessary for screening, including the screening methods configured for the property. #### Unit and Floor Plan The payload includes the `unit` the screening is for, along with its floor plan. Occupancy wins over the applied-for unit: whenever the household already occupies a unit, that is the unit reported, even when the application is for a different one. Only when the household occupies nothing does this fall back to the unit most recently assigned to the application, which is the usual case for a new applicant. A household part-way through a transfer reports the unit it still occupies, not the transfer destination, until the transfer completes. ```json { "screening": { "payload": { "unit": { "id": "7f3c1a20-0000-4000-8000-000000000010", "number": "101", "floorplan": { "id": "b8e4d5c6-0000-4000-8000-000000000020", "internalName": "A1", "marketingName": "The Aspen" } } } } } ``` Both floor plan names are provided separately: `internalName` is the name staff use inside Fortress — the floor plan endpoints expose this same value as `name` — and `marketingName` is the public-facing name. Either may be `null` on its own. Assigned units are not required in order to screen, so expect `null` in these cases — none is an error: * `unit` is `null` when the household has no unit assigned. * `unit.floorplan` is `null` when the unit has no floor plan assigned. * `unit` is also `null` when the unit could not be resolved as the screening was submitted. That lookup is deliberately non-blocking so it can never fail a screening, which means a transient failure is indistinguishable from an unassigned unit. `unit` is captured once when the screening is submitted and never recalculated, so it is absent entirely on screening requests created before this field was introduced, and a `null` is never backfilled afterwards. Treat a missing `unit` the same as `null`. #### Detecting Re-Screens Each applicant in the response includes a `previousScreening` field. When non-null, it signals that a prior screening exists for this applicant on the same property by your provider — which may indicate a re-screen or a duplicate submission. ```json { "screening": { "payload": { "applicants": [ { "firstName": "Jane", "lastName": "Smith", "dob": "1990-04-15", "previousScreening": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "requestId": "e5f6a7b8-0000-4000-8000-000000000002", "resultId": "c9d0e1f2-0000-4000-8000-000000000003", "status": "DECLINED", "screeningCreatedAt": "2026-02-10T14:00:00.000Z", "resultCreatedAt": "2026-02-10T14:05:00.000Z", "cancellationReasons": null } } ] } } } ``` When `previousScreening` is `null`, this is the applicant's first screening with your provider for this property. ### Step 3: Process the Screening Use the retrieved information to perform your screening checks (credit check, criminal background, eviction history, etc.). ### Step 4: Submit Screening Results Once processing is complete, submit the results back to Fortress: ```bash curl --location 'https://api.fortresstech.io/v1/screening-results' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "screeningRequestId": "89326590-fe06-4ae3-af71-07f1079e03a5", "idempotencyId": "44444234344444", "status": "DECLINED", "screeningMethods": [ { "screeningMethodId": "0410a383-7cbc-5dd0-bd0d-812f7f550902", "status": "DECLINED", "notes": "Credit check declined" }, { "screeningMethodId": "e8c61bad-aaa9-5eab-b2e5-5b4e6825f207", "status": "APPROVED", "notes": "Criminal background check passed" }, { "screeningMethodId": "ace88704-343d-5a87-bd7b-2e5a83cd8442", "status": "APPROVED", "notes": "No eviction history" } ] }' ``` **Important Notes:** * The number of `screeningMethods` in your submission must match the number of methods in the screening request details, or the request will be rejected * The overall `status` field represents the final screening result (APPROVED, DECLINED, etc.) * Each screening method has its own `status` representing the result of that specific check * After submission, the screening request status changes from `IN_PROGRESS` to the status you provided * Results are immediately reflected in the Fortress UI for property managers to review ### Step 5: Update Screening Results (Optional) If new data arrives after the initial submission — for example, a pending method result resolves — use `PATCH /screening-results` to update the existing result without re-submitting everything. You can update any combination of: * The overall `status`, `notes`, or `report` on the result record * Individual method details by their `screeningMethodId` Updating a result re-triggers Fortress automations, the same as the initial submission. > **Warning** > > Updates are blocked once a final decision has been recorded for the screening. The API returns `409 Conflict` in that case. **Update only the overall result status:** ```bash curl --location --request PATCH 'https://api.fortresstech.io/v1/screening-results' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "screeningRequestId": "89326590-fe06-4ae3-af71-07f1079e03a5", "status": "APPROVED", "notes": "All checks have now cleared" }' ``` **Update a specific pending method detail:** ```bash curl --location --request PATCH 'https://api.fortresstech.io/v1/screening-results' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "screeningRequestId": "89326590-fe06-4ae3-af71-07f1079e03a5", "status": "APPROVED", "screeningMethods": [ { "screeningMethodId": "d1e2f3a4-0000-4000-8000-000000000001", "status": "APPROVED", "notes": "Criminal background check now cleared" } ] }' ``` The `screeningMethodId` in each `screeningMethods` entry matches the `screeningMethodId` returned in the original `POST /screening-results` response. You can provide any number of method entries, or omit `screeningMethods` entirely to update only the top-level result fields. ## Available Endpoints | Endpoint | Summary | Method | | ---------------------------------------------------------------------------------------------- | ----------------------- | :----: | | [`/screening-requests`](/api-reference/screenings/list-screening-requests) | List Screening Requests | GET | | [`/screening-requests/{screeningRequestId}`](/api-reference/screenings/read-screening-request) | Get Screening Request | GET | | [`/screening-results`](/api-reference/screenings/create-screening-result) | Create Screening Result | POST | | [`/screening-results`](/api-reference/screenings/update-screening-result) | Update Screening Result | PATCH | ## Example: Creating Screening Results When creating screening results, you must provide individual results for each screening method configured for the property. ```json { "screeningRequestId": "22b1d66e-6ce9-4f01-90bb-9f8d99a95d4c", "idempotencyId": "049665d5-2a23-4f37-9c5e-da5dd30f5364", "providerIdentifier": "PROVIDER-12345", "status": "APPROVED", "screeningMethods": [ { "screeningMethodId": "f0336823-55ca-4375-8716-2c93c178bbe3", "status": "APPROVED", "notes": "Credit score: 720, excellent credit history" }, { "screeningMethodId": "a4bbe939-27ea-44fd-9607-56f37db184e2", "status": "APPROVED", "notes": "No criminal records found" }, { "screeningMethodId": "19af25c0-9623-4a80-ba16-34572b5bb5a2", "status": "APPROVED", "notes": "No prior evictions" } ] } ``` **Important**: The screening request response includes the `screeningMethods` array which shows all methods configured for the property. Your submission must include results for each of these methods. > Overview of the Screenings API endpoints and functionality ## API Docs - Screenings [List Screening Requests](https://developer.fortresstech.io/api-reference/screenings/list-screening-requests.md) - Screenings [Read Screening Request](https://developer.fortresstech.io/api-reference/screenings/read-screening-request.md) - Screenings [Create Screening Result](https://developer.fortresstech.io/api-reference/screenings/create-screening-result.md) - Screenings [Update Screening Result](https://developer.fortresstech.io/api-reference/screenings/update-screening-result.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://developer.fortresstech.io/openapi.json) - [OpenAPI YAML](https://developer.fortresstech.io/openapi.yaml)