The Subject object

A subject is one thing reviewers decide on inside an app review. 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. v1 can’t list subjects, assign reviewers, or record decisions yet.

The Subject object

{
  "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 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. 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. 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. `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. `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.
`ai_recommendation`	object or null	What AI Assist recommended. Only present with `expand=ai_recommendation`. See 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 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 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 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	`GET /v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}`
List Subject Filters	`GET /v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subject-filters`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Subject object

Attributes

Reviewers

Decisions

Removal

Evidence

AI recommendation

Expanding a subject

Subject filters

Endpoints

​Attributes

​Reviewers

​Decisions

​Removal

​Evidence

​AI recommendation

​Expanding a subject

​Subject filters

​Endpoints

Attributes

Reviewers

Decisions

Removal

Evidence

AI recommendation

Expanding a subject

Subject filters

Endpoints