> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Subject object

> A subject is one thing under review in an app review: an account, or one entitlement an account holds. This page covers its reviewers, decision, removal, and AI recommendation.

A subject is one thing reviewers decide on inside an
[app review](https://docs.lumos.com/reference/v1/objects/access-review.md#app-reviews). In an `accounts` review, each
subject is an account. In an `entitlements` review, each subject is one entitlement that an account
holds. `subject_type` says which, and every subject in one app review has the same type.

You read one subject at a time with [Get Subject](https://docs.lumos.com/api-reference/v1/access-reviews/get-subject.md).
v1 can't list subjects, assign reviewers, or record decisions yet.

```json The Subject object theme={null}
{
  "id": "8b9c0d1e-2f3a-4b5c-9d6e-7f8a9b0c1d2e",
  "subject_type": "account-entitlement",
  "account_name": "jane.doe",
  "identity": {
    "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "email": "jane.doe@acme.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "status": "active"
  },
  "reviewers": [
    {
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "group_id": null,
      "group_name": null,
      "email": "sam.lee@acme.com",
      "given_name": "Sam",
      "family_name": "Lee"
    }
  ],
  "entitlement": {
    "id": "4d5e6f70-8192-4a3b-8c4d-5e6f70819203",
    "label": "Maintainer",
    "type": "Role"
  },
  "decision": "reject-access",
  "decided_by": {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
    "email": "sam.lee@acme.com",
    "given_name": "Sam",
    "family_name": "Lee",
    "status": "active"
  },
  "decided_at": "2026-11-02T15:20:00Z",
  "note": "Moved to the data team.",
  "removal": {
    "status": "completed",
    "method": "automated",
    "assignees": [],
    "error": null
  },
  "evidence_required_by": null,
  "is_evidence_attached": false
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | The subject's ID. Always present. |
| `subject_type` | string | `account` or `account-entitlement`. Follows from the app review's `review_type`. Always present. |
| `account_name` | string or null | The account's name in the app. |
| `identity` | object or null | The Lumos [user](https://docs.lumos.com/reference/v1/objects/user.md) the account belongs to. `null` for an account Lumos hasn't matched to a user. Lumos still reviews it. |
| `reviewers` | array | The users and groups who decide on the subject. See [Reviewers](#reviewers). Empty until Lumos assigns reviewers. |
| `entitlement` | object or null | The entitlement under review, `{id, label, type}`. Only present when `subject_type` is `account-entitlement`. |
| `decision` | string | What the reviewer decided. See [Decisions](#decisions). Always present. |
| `decided_by` | object or null | The user who made the decision. |
| `decided_at` | string or null | When the decision was made. |
| `note` | string or null | The note the reviewer left for the auditor with the decision. |
| `removal` | object or null | The removal the decision led to. See [Removal](#removal). `null` when the decision keeps the access, or removals haven't started. |
| `evidence_required_by` | string or null | Why evidence is owed for the subject. See [Evidence](#evidence). `null` when nothing asks for evidence. |
| `is_evidence_attached` | boolean or null | Whether any evidence is attached to the subject. |
| `evidence` | array | The files attached as evidence. Only present with `expand=evidence`. See [Evidence](#evidence). |
| `ai_recommendation` | object or null | What AI Assist recommended. Only present with `expand=ai_recommendation`. See [AI recommendation](#ai-recommendation). |

## Reviewers

Each item in `reviewers`, and in `removal.assignees`, is a user or a group:

| Field | Description |
| - | - |
| `id` | The user's ID. `null` when a group holds the assignment. |
| `group_id` | The group's ID, when a group holds the assignment. |
| `group_name` | The group's name, when a group holds the assignment. |
| `email` | The user's email. |
| `given_name` | The user's given name. |
| `family_name` | The user's family name. |

## Decisions

| `decision` | Meaning |
| - | - |
| `pending` | Nobody has decided yet. |
| `approve-access` | The reviewer kept the access. |
| `reject-access` | The reviewer rejected the access. |
| `modify-access` | The reviewer chose to change the access rather than keep or remove it. |
| `reviewing-permissions` | The reviewer is reviewing the account's entitlements. Only on an `account` subject. |

## Removal

`removal` describes how Lumos takes away access a reviewer rejected or modified:

| Field | Description |
| - | - |
| `status` | How far the removal has progressed. See the table below. It updates while the removal runs. |
| `method` | `automated` when a workflow removed the access with no manual task, or `manual` when a person did. `null` until `status` is `completed`. |
| `assignees` | The people assigned to remove the access by hand. For an entitlement, it also lists the people assigned on its account. |
| `error` | Why the last attempt failed, as `{code, message}`. See below. |
| `itsm_ticket` | The ticket tracking the removal, `{external_id, url}`. Only present with `expand=removal.itsm_ticket`. |

| `status` | Meaning |
| - | - |
| `in-progress` | Lumos is removing the access. |
| `waiting-manual-step` | The removal's workflow is waiting for a person to act. |
| `manual-removal` | The removal is left to a person, with no workflow to track it. |
| `failed` | The removal failed. |
| `completed` | The access was removed. |

`status` describes only the removal. A removal reads `completed` even while evidence of it is
still owed, which `evidence_required_by` reports.

`error.code` names the step that failed. It isn't a fixed set, so don't branch on it.
`error.message` is what the integration or workflow reported.

`error` can be `null` even when `status` is `failed`. When a removal waits on a
[task](https://docs.lumos.com/reference/v1/objects/task.md) for a person to act on, its `error` clears only once that person
acts on the task.

## Evidence

Evidence sits on the subject, beside `removal`, because a subject whose access was kept can owe
evidence too. `evidence_required_by` gives the highest-ranked reason that applies:

| `evidence_required_by` | Meaning |
| - | - |
| `review-setting-all-removals` | The app review asks for evidence on every removal. |
| `decision-reason` | The reason given with the decision asks for evidence. |
| `manual-action` | A person acted on the removal, or still has to. |
| `no-removal-request` | No workflow could remove the access. |

`is_evidence_attached` says whether any file is attached. With `expand=evidence`, each item in
`evidence` has `filename`, `content_type`, `description`, `uploaded_by`, and `uploaded_at`. v1
doesn't download or upload evidence files.

## AI recommendation

`expand=ai_recommendation` adds what AI Assist recommended, if it reached a recommendation. On an
app review where AI Assist is off, the call returns `400` with `code` `app_review.ai_disabled`.

| Field | Description |
| - | - |
| `decision` | `auto-approve` or `auto-reject` for a firm recommendation, `suggest-approve` or `suggest-reject` for a weaker one, or `unclear`. |
| `decision_category` | The kind of finding behind it, such as `Unusual Access`. Free text, so group on it but don't branch on it. |
| `reasoning` | Why AI Assist made the recommendation. |

## Expanding a subject

[Get Subject](https://docs.lumos.com/api-reference/v1/access-reviews/get-subject.md) takes these in `expand`, separated by
commas: `ai_recommendation`, `evidence`, and `removal.itsm_ticket`. A field you don't ask
for is absent from the response, not `null`. Any other value returns `400`.

## Subject filters

[List Subject Filters](https://docs.lumos.com/api-reference/v1/access-reviews/list-subject-filters.md) lists the fields an
app review's subjects can be filtered on. Each field comes with the operators it supports and, when
it has a fixed set of values, the values it accepts. The list depends on how far the review has
progressed. A decision filter appears once the review launches, and a removal filter once
removals start. No v1 endpoint takes subject filters yet.

## Endpoints

| Endpoint | Path |
| - | - |
| [Get Subject](https://docs.lumos.com/api-reference/v1/access-reviews/get-subject.md) | `GET /v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}` |
| [List Subject Filters](https://docs.lumos.com/api-reference/v1/access-reviews/list-subject-filters.md) | `GET /v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subject-filters` |