# Data Access Requests A **Data Access Request** is a request submitted by authorized users to access data provided by a [Trusted Research Environment (TRE)](/developer/api/trusted-research-environments.md). In the API, Data Access Requests are represented as TRE application objects with IDs prefixed `treApplication-`. Authorized users or TRE reviewers create these access requests by specifying the requested data (cohort and fields), and each request goes through a configurable multi-step review workflow before data access is granted. In this reference, use "access request" for the user-facing concept and "application" only when citing API identifiers or field names. If you want to manage data access requests in the Platform UI, see [Submit a Data Access Request](/user/trusted-research-environments/submitting-access-request.md) and [Review Data Access Requests](/user/trusted-research-environments/reviewing-access-requests.md). {% hint style="info" %} Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} ## Data Access Request States A data access request progresses through the following lifecycle states: * `"draft"` The initial state after creation. The request owner or a reviewer can edit the access request details. * `"in-review"` The access request has been submitted and is awaiting review. Individual review steps are resolved by assigned reviewers. * `"approved"` All review steps have been approved. The request owner and collaborators can create projects and dispense data. * `"in-revision"` One or more review steps have been rejected. The request owner can modify the access request and resubmit it for review. ## Data Access Request Roles Three roles interact with a data access request: * **Request Owner** The user who owns the access request. In the API, the request owner is represented by the `applicant` field. The request owner can edit, submit, and delete the access request, and manage collaborators. By default, the request owner is the user who created the access request. A TRE reviewer can create an access request on behalf of another user by specifying the `applicant` field. * **Collaborator** Users added by the request owner who gain view access to the access request details, view-only access to the cohort in the Cohort Browser, and access to projects created from the access request. * **Reviewer** TRE reviewers assigned to specific [review steps](/developer/api/trusted-research-environments.md#data-access-request-review-steps) who can approve or reject the access request for their assigned steps. Reviewers can view all access request details, including review step decisions and approval history. ## Review Decisions Each review step must be independently resolved by at least one reviewer assigned to that step. The overall access request decision is determined by the following priorities: | Priority | Condition | Overall decision | | -------- | ------------------------------------------ | ---------------- | | 1 | Any review step is rejected | Rejected | | 2 | No rejected steps, but any step is pending | Pending | | 3 | All steps are approved | Approved | When all steps are approved, the access request transitions to `approved` state. If any step is rejected, the access request transitions to `in-revision` state, allowing the request owner to revise and resubmit. ## Cohort Metadata Each Data Access Request can store one or more cohort metadata records that capture the cohort definitions used during data dispensal. A cohort metadata record contains a name, an optional description, and a details mapping that holds the cohort filter definition (for example, Cohort Browser filter criteria). Cohort metadata records are managed independently from the access request through dedicated sub-resource methods: * [`/treApplication-xxxx/createCohortMetadata`](#api-method-treapplication-xxxx-createcohortmetadata) * [`/treApplication-xxxx/updateCohortMetadata`](#api-method-treapplication-xxxx-updatecohortmetadata) * [`/treApplication-xxxx/removeCohortMetadata`](#api-method-treapplication-xxxx-removecohortmetadata) * [`/treApplication-xxxx/describeCohortMetadata`](#api-method-treapplication-xxxx-describecohortmetadata) The resulting record IDs are referenced in the `cohortMetadataRecords` field when creating or updating an access request via [`/treApplication/new`](#api-method-treapplication-new) or [`/treApplication-xxxx/update`](#api-method-treapplication-xxxx-update). The request owner and collaborators can create, update, and remove cohort metadata records. TRE reviewers have read-only access through the describe method. ## Dispensal When a Data Access Request reaches the `approved` state, the request owner and collaborators can create projects from the request. By default, creating a project from an approved request starts dispensal, which provisions the approved cohort and fields — including bulk files and tabular datasets — into the project. Dispensal can be disabled at project creation time by setting `tre.dispense` to `false` in [`/project/new`](/developer/api/data-containers/projects.md#api-method-project-new). Dispensal always uses the most current active inventory version at the time the dispensal job is launched. If a newer inventory version becomes active after the request is approved, the platform applies the approved cohort and field selections to that newer version. Data providers are expected to maintain field compatibility across inventory versions, ensuring that approved queries remain executable on newer data releases. Dispensed data is protected. Objects placed into a TRE project by the dispensal process cannot be deleted by any user. Attempting to remove dispensed objects returns a `PermissionDenied` error. Dispensed data is removed only when the entire project is destroyed. For more information about this restriction, see [Non-Configurable Restrictions](/developer/api/trusted-research-environments.md#non-configurable-restrictions) in the TRE API reference. ## API Method Specifications ### API Method: `/treApplication/new` #### Specification Creates a new Data Access Request (TRE application object) in `draft` state. The requesting user must be an authorized user of the TRE, or a TRE reviewer if specifying an `applicant` on behalf of another user. The TRE must be in `active` state. #### Inputs * `title` **string** (required) A short title for the access request, up to 256 characters. * `summary` **string** (required) A detailed description of the access request, up to 5,000 characters. * `treId` **string** (required) The ID of the TRE where the access request is being submitted. * `cohortMetadataRecords` **array of strings** (optional) A list of record IDs representing the cohort. Must be omitted when the TRE has `enforceFullCohortSelection` enabled. * `fields` **array of strings** (required) A list of field identifiers requested by the applicant. * `applicant` **string** (optional) The user ID of the applicant. Only TRE reviewers can specify this field to create an access request on behalf of another authorized user. Defaults to the requesting user. #### Outputs * `id` **string** ID of the newly created TRE application object (for example, `treApplication-B0FJgXy4Zg231jgbQ9zQ0003`). #### Errors * InvalidInput * `title` exceeds 256 characters * `summary` exceeds 5,000 characters * `applicant` is specified but is not an authorized user of the TRE * `cohortMetadataRecords` cannot be set when the TRE has `enforceFullCohortSelection` enabled * InvalidState * The TRE is not in `active` state * ResourceNotFound * The TRE specified in `treId` was not found * One or more records in `cohortMetadataRecords` were not found * The `applicant` user was not found * PermissionDenied * If `applicant` is specified, the requesting user must be a TRE reviewer * If `applicant` is not specified, the requesting user must be an authorized user of the TRE * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/update` #### Specification Updates an existing Data Access Request. The request must be in `draft` or `in-revision` state, and the TRE must be in `active` state. The requesting user must be the applicant or a TRE reviewer. #### Inputs * `title` **string** (optional) A short title for the access request, up to 256 characters. * `summary` **string** (optional) A detailed description of the access request, up to 5,000 characters. * `cohortMetadataRecords` **array of strings** (optional) A list of record IDs representing the cohort. * `fields` **array of strings** (optional) A list of field identifiers requested by the applicant. #### Outputs * `id` **string** ID of the modified access request. #### Errors * InvalidInput * `title` exceeds 256 characters * `summary` exceeds 5,000 characters * `cohortMetadataRecords` cannot be set when the TRE has `enforceFullCohortSelection` enabled * InvalidState * The TRE is not in `active` state * The access request is not in `draft` or `in-revision` state * ResourceNotFound * The access request was not found * One or more records in `cohortMetadataRecords` were not found * PermissionDenied * The requesting user must be the applicant or a TRE reviewer ### API Method: `/treApplication-xxxx/createCohortMetadata` #### Specification Creates a new cohort metadata record for the access request. The record stores the cohort definition that the platform uses during data dispensal. The requesting user must be the applicant or a collaborator of the access request. #### Inputs * `name` **string** (required) A descriptive name for the cohort. * `description` **string** (optional) A description of the cohort. * `details` **mapping** (required) The cohort filter definition, for example, Cohort Browser filter criteria. #### Outputs * `id` **string** The record ID of the newly created cohort metadata record. #### Errors * InvalidInput * `name` is not provided or is empty * `details` is not provided or is empty * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be the applicant or a collaborator of the access request * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/updateCohortMetadata` #### Specification Updates an existing cohort metadata record for the access request. The requesting user must be the applicant or a collaborator of the access request. #### Inputs * `recordId` **string** (required) The record ID of the cohort metadata record to update. * `name` **string** (optional) A descriptive name for the cohort. * `description` **string** (optional) A description of the cohort. * `details` **mapping** (optional) The cohort filter definition. #### Outputs * `id` **string** The record ID of the updated cohort metadata record. #### Errors * ResourceNotFound * The access request was not found * The specified `recordId` was not found * PermissionDenied * The requesting user must be the applicant or a collaborator of the access request * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/removeCohortMetadata` #### Specification Deletes a cohort metadata record from the access request. The requesting user must be the applicant or a collaborator of the access request. #### Inputs * `recordId` **string** (required) The record ID of the cohort metadata record to delete. #### Outputs * `id` **string** The record ID of the deleted cohort metadata record. #### Errors * ResourceNotFound * The access request was not found * The specified `recordId` was not found * PermissionDenied * The requesting user must be the applicant or a collaborator of the access request * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/describeCohortMetadata` #### Specification Describes a cohort metadata record for the access request. The requesting user must be the applicant, a collaborator, or a TRE reviewer. #### Inputs * `recordId` **string** (required) The record ID of the cohort metadata record to describe. #### Outputs * `id` **string** The record ID. * `name` **string** The name of the cohort. * `description` **string** The description of the cohort. * `details` **mapping** The cohort filter definition. * `created` [**timestamp**](/developer/api.md#data-types) When the record was created. * `modified` [**timestamp**](/developer/api.md#data-types) When the record was last modified. #### Errors * ResourceNotFound * The access request was not found * The specified `recordId` was not found * PermissionDenied * The requesting user must be the applicant, a collaborator, or a TRE reviewer * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/submit` #### Specification Submits an access request for review. The access request must be in `draft` or `in-revision` state, and the TRE must be in `active` state. On submission, all review step statuses are reset to `in-review`, and submission actions are recorded in `approvalHistory` for each review step. Email notifications are sent to the assigned reviewers, and a submission confirmation is sent to the submitting user. The requesting user must be the applicant or a TRE reviewer. #### Inputs * `message` **string** (optional) A message to include with the submission, up to 1,000 characters. #### Outputs * `id` **string** ID of the submitted access request. #### Errors * InvalidInput * `message` exceeds 1,000 characters * InvalidState * The access request is not in `draft` or `in-revision` state * The TRE is not in `active` state * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be the applicant or a TRE reviewer * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/approve` #### Specification Approves a specific review step in the access request approval workflow. The access request must be in `in-review` state and the TRE must be in `active` state. The step decision is recorded in `approvalHistory`, and a confirmation email is sent to the current reviewers. If all review steps are approved after this action, the access request transitions to `approved` state and the applicant is notified. If the TRE uses a customized rate card, a wallet is created for the applicant and collaborators on approval. The requesting user must be a reviewer assigned to the specified review step. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step to approve. * `message` **string** (optional) A message to include with the approval decision, up to 1,000 characters. #### Outputs * `id` **string** ID of the approved access request. #### Errors * InvalidInput * `reviewStepId` does not match a valid review step * `message` exceeds 1,000 characters * InvalidState * The access request is not in `in-review` state * The TRE is not in `active` state * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be a reviewer assigned to the specified review step * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/reject` #### Specification Rejects a specific review step in the access request approval workflow. The access request must be in `in-review` state. The step decision is recorded in `approvalHistory`, and a confirmation email is sent to the current reviewers. If any review step is rejected, the access request transitions to `in-revision` state, allowing the applicant to modify and resubmit the access request. The requesting user must be a reviewer assigned to the specified review step. #### Inputs * `reviewStepId` **string** (required) The identifier of the review step to reject. * `message` **string** (optional) A message to include with the rejection decision, up to 1,000 characters. #### Outputs * `id` **string** ID of the rejected access request. #### Errors * InvalidInput * `reviewStepId` does not match a valid review step * `message` exceeds 1,000 characters * InvalidState * The access request is not in `in-review` state * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be a reviewer assigned to the specified review step * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/delete` #### Specification Deletes an access request. The access request can only be deleted if there are no projects associated with it, and the access request is hard deleted. If the TRE uses a customized rate card and the access request is in `approved` state, the associated wallet (org) is destroyed. The requesting user must be the applicant. #### Inputs None. #### Outputs * `id` **string** ID of the deleted access request. #### Errors * InvalidState * The access request has projects associated with it and cannot be deleted * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be the applicant * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/describe` #### Specification Describes a Data Access Request. The output depends on the requesting user's role. Applicants and collaborators see the default access request fields. TRE reviewers see additional review step details and approval history. #### Inputs * `fields` **mapping** (optional) Specifies fields to include or exclude from the output. * **key** — requested output field (see "Outputs" section for valid values). * **value** **boolean** — whether to include the field. #### Outputs The following fields are available to all users who have access to the access request (applicant, collaborators, and reviewers): * `id` **string** The access request ID. * `title` **string** The title of the access request. * `summary` **string** The detailed description of the access request. * `cohortMetadataRecords` **array of strings** The record IDs representing the cohort. * `cohortAccess` **string** The level of access the requesting user has to the cohort. Collaborators and reviewers have `"VIEW"` access. The applicant has `"EDIT"` access. * Must be one of `"VIEW"` or `"EDIT"`. * `fields` **array of strings** The field identifiers requested in the access request. * `treId` **string** The TRE ID. * `state` **string** The current state of the access request. * Must be one of `"draft"`, `"in-review"`, `"approved"`, or `"in-revision"`. * `applicant` **string** The user ID of the applicant. * `collaborators` **array of strings** The user IDs of collaborators. * `overallReviewDecision` **string** The aggregate review decision across all steps. See [Review Decisions](#review-decisions). * Must be one of `"Approved"`, `"Pending"`, or `"Rejected"`. * `messages` **array of mappings** Messages from the applicant and reviewers. * `createdBy` **string** The user ID of the access request creator. * `created` [**timestamp**](/developer/api.md#data-types) When the access request was created. * `modifiedBy` **string** The user ID of the user who last modified the access request. * `modified` [**timestamp**](/developer/api.md#data-types) When the access request was last modified. The following fields are available only to TRE reviewers: * `approvals` **array of mappings** The current status of each review step, including the review step ID and its state. * `approvalHistory` **array of mappings** A complete history of actions taken on the access request, including submissions, approvals, and rejections with timestamps and user IDs. #### Errors * ResourceNotFound * The access request was not found * PermissionDenied * The requesting user must be the applicant, a collaborator, or a TRE reviewer * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/addCollaborators` #### Specification Adds collaborators to an access request. Collaborators gain view access to the access request details, view-only access to the cohort in the Cohort Browser, and can create projects from the approved access request. The requesting user must be the applicant. Collaborators can be added in any access request state. If the TRE uses a customized rate card and the access request has an associated wallet, new collaborators are added as wallet members. #### Inputs * `users` **array of strings** (required) A list of user IDs to add as collaborators. * The total number of collaborators must not exceed 100. * Each collaborator must be an authorized user of the TRE (or a member of an authorized org, or any user if the TRE authorized users include `PUBLIC`). #### Outputs * `id` **string** ID of the modified access request. #### Errors * InvalidInput * `users` is not provided or the list is empty * Adding these users would exceed the limit of 100 collaborators * One or more users are not authorized users of the TRE * ResourceNotFound * The access request was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be the applicant * The requesting user must use a full-scope token ### API Method: `/treApplication-xxxx/removeCollaborators` #### Specification Removes collaborators from an access request. Removed collaborators are removed from all projects associated with the access request, regardless of their role in those projects. This includes cases where the removed user is the only admin or only member of a project. If the TRE uses a customized rate card, removed collaborators are also removed from the associated wallet (org). The requesting user must be the applicant. #### Inputs * `users` **array of strings** (required) A list of user IDs to remove from the collaborators list. #### Outputs * `id` **string** ID of the modified access request. #### Errors * InvalidInput * `users` is not provided or the list is empty * ResourceNotFound * The access request was not found * One or more users in the list do not exist * PermissionDenied * The requesting user must be the applicant * The requesting user must use a full-scope token --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.dnanexus.com/developer/api/trusted-research-environments/data-access-requests.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.