Screening Overview

Use the Screening API to retrieve screening requests, view their details, and submit updated results.

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

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.

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

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.