---
title: "Record or withdraw research consent"
method: POST
path: "/api/v1/subjects/{subject_id}/research-consent"
tags: ["canonical"]
---

# Record or withdraw research consent

`POST /api/v1/subjects/{subject_id}/research-consent`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/subjects/{subject_id}/research-consent`
- Auth: HTTP bearer

Record a separate, attributed subject decision about behavioral-model research participation.

## Path parameters

- `subject_id` string, required

## Request body

- ResearchConsentRequest: Record or revoke subject research consent separately from ordinary service use and subject creation.
  - `consented` boolean, required: Strict JSON boolean: true records consent and false records withdrawal. The server fixes the receipt purpose and disclosure version. Deployment eligibility is configured separately.

## Response `200`

Current subject record. The consent receipt is stored separately; session research eligibility is reported when creating a session.

- Subject: Pseudonymous subject lifecycle record within one environment.
  - `adaptation_frozen` boolean, required: Whether online template adaptation is frozen; true prevents silent template adaptation.
  - `anchor` string, required: Account anchor established by the customer identity process and recorded by GrayPass.
  - `created_at` string, required: Creation time as an ISO 8601 timestamp.
  - `enrollment_state` 'not_enrolled' | 'enrolling' | 'enrolled' | 'revoked' | 'deleted', required: Current enrollment lifecycle state. Revoked subjects need the configured recovery path; deleted subjects are no longer operationally retrievable.
  - `environment` string, required: Environment identifier that scopes this record; sandbox and live resources are separate.
  - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
  - `limitations` string[]: Applicable limitations that must accompany interpretation of the result.
  - `recovery_policy` string, required: Recovery rule governing whether re-enrollment requires an anchor or a separate manual-review process.
  - `revoked_at` string, nullable: Revocation time as an ISO 8601 timestamp, or null when not revoked.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)