Screening Overview

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:

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:

$
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:

1
[
2
  {
3
    "id": "6e46a1d7-503a-42fa-a55b-047ee04b5279",
4
    "propertyId": "123e4567-e89b-12d3-a456-426614174000",
5
    "idempotencyId": "abc123",
6
    "status": "IN_PROGRESS"
7
  }
8
]

Step 2: Get Detailed Screening Information

For each pending request, retrieve the complete screening details including customer and household information:

$
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.

1
{
2
  "screening": {
3
    "payload": {
4
      "unit": {
5
        "id": "7f3c1a20-0000-4000-8000-000000000010",
6
        "number": "101",
7
        "floorplan": {
8
          "id": "b8e4d5c6-0000-4000-8000-000000000020",
9
          "internalName": "A1",
10
          "marketingName": "The Aspen"
11
        }
12
      }
13
    }
14
  }
15
}

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.

1
{
2
  "screening": {
3
    "payload": {
4
      "applicants": [
5
        {
6
          "firstName": "Jane",
7
          "lastName": "Smith",
8
          "dob": "1990-04-15",
9
          "previousScreening": {
10
            "id": "a1b2c3d4-0000-4000-8000-000000000001",
11
            "requestId": "e5f6a7b8-0000-4000-8000-000000000002",
12
            "resultId": "c9d0e1f2-0000-4000-8000-000000000003",
13
            "status": "DECLINED",
14
            "screeningCreatedAt": "2026-02-10T14:00:00.000Z",
15
            "resultCreatedAt": "2026-02-10T14:05:00.000Z",
16
            "cancellationReasons": null
17
          }
18
        }
19
      ]
20
    }
21
  }
22
}

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:

$
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.

Update only the overall result status:

$
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:

$
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

Example: Creating Screening Results

When creating screening results, you must provide individual results for each screening method configured for the property.

1
{
2
  "screeningRequestId": "22b1d66e-6ce9-4f01-90bb-9f8d99a95d4c",
3
  "idempotencyId": "049665d5-2a23-4f37-9c5e-da5dd30f5364",
4
  "providerIdentifier": "PROVIDER-12345",
5
  "status": "APPROVED",
6
  "screeningMethods": [
7
    {
8
      "screeningMethodId": "f0336823-55ca-4375-8716-2c93c178bbe3",
9
      "status": "APPROVED",
10
      "notes": "Credit score: 720, excellent credit history"
11
    },
12
    {
13
      "screeningMethodId": "a4bbe939-27ea-44fd-9607-56f37db184e2",
14
      "status": "APPROVED",
15
      "notes": "No criminal records found"
16
    },
17
    {
18
      "screeningMethodId": "19af25c0-9623-4a80-ba16-34572b5bb5a2",
19
      "status": "APPROVED",
20
      "notes": "No prior evictions"
21
    }
22
  ]
23
}

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.