# Get Request

Endpoint: GET /{requestId}
Version: 1.0
Security: oauth2

## Path parameters:

  - `requestId` (string, required)
    Unique ID of the request.

## Query parameters:

  - `expand` (string)
    Comma separated list of related data to return on each request. Supported values: controls, labels, proof. Linked items the caller is not permitted to see are omitted. For an auditor, proof is returned only once the request has been submitted to them

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique identifier for the request
    Example: "d4e5f6a7-b8c9-0123-abcd-ef4567890123"

  - `orgId` (string, required)
    The unique identifier of the organization the request belongs to
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `index` (integer)
    The index of the request used for generating unique references/identifiers of requests
    Example: 1

  - `parentId` (string, required)
    The unique identifier of the parent object (e.g. audit, assessment)
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `parentType` (string)
    The type of the object.
    Enum: "assessment", "audit", "connection", "control", "controlScope", "domain", "freshnessHistory", "exportFile", "label", "organization", "organizationUser", "policy", "program", "proof", "request", "requirement", "risk", "riskRegister", "section", "task", "scope", "template", "user"

  - `parentName` (string)
    The name of the parent object (e.g. audit, assessment)
    Example: "Q4 2024 SOC2 Audit"

  - `parentWorkStatus` (string)
    The work status of a parent object (e.g. audit, assessment)
    Enum: "active", "completed"

  - `reference` (string)
    A user-defined identifier for the request. The property is omitted when the request has no reference
    Example: "REF-001"

  - `summary` (string, required)
    The summary of the request
    Example: "Provide access control documentation"

  - `description` (string)
    The description of the request
    Example: "Please provide documentation of access control policies and procedures."

  - `assigneeId` (string)
    The unique identifier of the assignee for the request
    Example: "a7b8c9d0-e1f2-3456-abcd-ef1234567890"

  - `workItemStatus` (string, required)
    The work item status of a request. Valid values depend on the parent object type (e.g. audit, assessment)
    Enum: "notStarted", "inProgress", "internalReview", "submittedToAuditor", "needsRevision", "closed", "approved"

  - `priority` (string)
    The priority level.
    Enum: "highest", "high", "medium", "low", "lowest"

  - `dueDate` (string)
    The due date for the request (ISO-8601 format)
    Example: "2024-12-31 12:00:00+00:00"

  - `key` (string)
    A computed key for the request (e.g. REQ-1)
    Example: "REQ-1"

  - `isPrivate` (boolean)
    Whether the request is private

  - `groupId` (string)
    The unique identifier of the group assigned to the request

  - `clonedRequestId` (string)
    The unique identifier of the request this was cloned from, if applicable

  - `status` (string)
    The status of the object.
    Enum: "active", "archived", "pending", "canceled", "deleted", "closed"

  - `createdBy` (string)
    The unique identifier of the user who created the request
    Example: "a7b8c9d0-e1f2-3456-abcd-ef1234567890"

  - `createdOn` (string)
    The date and time the request was created (ISO-8601 format)
    Example: "2024-10-01 08:00:00+00:00"

  - `updatedBy` (string)
    The unique identifier of the user who last updated the request
    Example: "a7b8c9d0-e1f2-3456-abcd-ef1234567890"

  - `updatedOn` (string)
    The date and time the request was last updated (ISO-8601 format)
    Example: "2024-10-15 14:30:00+00:00"

  - `permissions` (array)
    List of permissions the API user has on the request
    Example: []

  - `_isPartialData` (boolean)
    This is true when the user does not have read permissions on the request

  - `customFields` (array)
    The list of custom field values for the request
    Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]

  - `customFields.fieldId` (string)
    Unique identifier for the custom field

  - `customFields.fieldName` (string)
    Name of the custom field

  - `customFields.fieldType` (string)
    Type of field
    Enum: "text", "number", "date", "user", "textSingleSelect", "textMultiSelect"

  - `customFields.numberFormat` (string)
    Format if the field type is number
    Enum: "decimal", "percentage"

  - `customFields.textValue` (string)
    Value if the field type is text

  - `customFields.numberValue` (number)
    Value if the field type is number

  - `customFields.dateValue` (string)
    Value if the field type is date

  - `customFields.userValue` (string)
    Value if the field type is user

  - `customFields.selection` (string)
    Value for textSingleSelect

  - `customFields.selections` (array)
    List of values for textMultiSelect

  - `controls` (array)
    The controls linked to the request. Included when the expand query contains 'controls'
    Example: [{"id":"d88d505d-5199-11ee-a644-522476618ae8","orgId":"ce83e3cd-5199-11ee-a644-522476618ae8","controlType":"scopeAssignment","controlIdentifier":"SOC2-P4.1.1_Legal","name":"Include in the privacy notice the use of collected personal information","scopeName":"Legal","flatScopeParent":false,"flatScopeAssignment":true,"scopeId":"f16f2f96-5199-11ee-a644-522476618ae8","scopeType":"scopeAssignment","parentId":"b6a6c2f0-5199-11ee-a644-522476618ae8","rootId":"b6a6c2f0-5199-11ee-a644-522476618ae8","description":"The privacy notice identifies the use of collected personal information.","notes":"","domainId":"d7cf0a26-5199-11ee-a644-522476618ae8","domainName":"Privacy","freshnessPolicy":"manual","freshForDuration":"PT720H","freshness":"fresh","freshAsOfDate":"2025-01-12T18:26:10.00.5365Z","freshAsOfNote":"Initial freshness set","implementation":"inProgress","testingStatus":"effective","testingDeficiency":[],"computeTestingStatus":false,"automation":"partial","health":"notAvailable","overrideHealth":false,"owner":{"id":"d2363cab-5199-11ee-a644-522476618ae8","type":"activeUser","userId":"82d7c228-8bcd-11e9-a94b-ab3de8494987","email":"jane.doe@example.com","givenName":"Jane","surname":"Doe","language":"en","locale":"US","timeZone":"America/Los_Angeles","status":"active"},"customFields":[{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}],"status":"active","createdBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","createdOn":"2023-09-12T18:26:10.005365Z","updatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","updatedOn":"2023-09-12T18:26:10.005365Z","permissions":[]}]

  - `controls.id` (string)
    The unique identifier for the control
    Example: "d88d505d-5199-11ee-a644-522476618ae8"

  - `controls.orgId` (string)
    The unique identifier for the organization
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `controls.controlType` (string)
    Type of control
    Enum: "simple", "parent", "scopeAssignment"

  - `controls.controlIdentifier` (string)
    The human readable unique identifier for the control within the organization
    Example: "SOC2-P4.1.1_Legal"

  - `controls.name` (string)
    The name of the control
    Example: "Include in the privacy notice the use of collected personal information"

  - `controls.scopeName` (string)
    Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'
    Example: "Legal"

  - `controls.flatScopeParent` (boolean)
    Equivalent to controlType == parent. True for any control that has scope assignments.

  - `controls.flatScopeAssignment` (boolean)
    Equivalent to controlType == scopeAssignment. True for scoped controls.
    Example: true

  - `controls.scopeId` (string)
    Identifier of the scope this control is associated with. Populated on scoped controls (and on parent controls in hierarchical scopes).
    Example: "f16f2f96-5199-11ee-a644-522476618ae8"

  - `controls.scopeType` (string)
    Role of this control in a hierarchical scope tree. Returned for organizations using hierarchical scopes.
    Enum: "simple", "root", "parent", "scopeAssignment"

  - `controls.parentId` (string)
    For organizations using hierarchical scopes, the identifier of the immediate parent control in the scope tree. Empty for root and simple controls.
    Example: "b6a6c2f0-5199-11ee-a644-522476618ae8"

  - `controls.rootId` (string)
    For organizations using hierarchical scopes, the identifier of the root of the scope tree this control belongs to. On root controls, equals id.
    Example: "b6a6c2f0-5199-11ee-a644-522476618ae8"

  - `controls.description` (string)
    The description of the control
    Example: "The privacy notice identifies the use of collected personal information."

  - `controls.notes` (string)
    Additional notes about the control

  - `controls.domainId` (string)
    The unique identifier of the domain
    Example: "d7cf0a26-5199-11ee-a644-522476618ae8"

  - `controls.domainName` (string)
    The name of the domain
    Example: "Privacy"

  - `controls.freshnessPolicy` (string)
    The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
    Enum: "none", "manual"

  - `controls.freshForDuration` (string)
    The duration after which control becomes stale
    Example: "PT720H"

  - `controls.freshness` (string)
    The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.
    Enum: "noFreshness", "fresh", "expired", "unknown"

  - `controls.freshAsOfDate` (string)
    The date when freshness was last marked 'fresh'
    Example: "2025-01-12T18:26:10.00.5365Z"

  - `controls.freshAsOfNote` (string)
    The note populated when the control was marked fresh
    Example: "Initial freshness set"

  - `controls.implementation` (string)
    Implementation status
    Enum: "unknown", "notStarted", "inProgress", "completed"

  - `controls.testingStatus` (string)
    Testing status
    Enum: "notTested", "inProgress", "effective", "ineffective"

  - `controls.testingDeficiency` (array)
    Design deficiency: The control, as designed, is inadequate to meet its intended objective. Operation deficiency: The control’s design is sound, but it is not being executed or followed as intended in practice.
    Enum: "design", "operation"

  - `controls.computeTestingStatus` (boolean)
    Whether testing status is computed automatically

  - `controls.automation` (string)
    Determines whether this control can be automated and its current status
    Enum: "notStarted", "partial", "fullyAutomated", "cantAutomate"

  - `controls.health` (string)
    Whether the health status is available and its current status
    Enum: "critical", "atRisk", "healthy", "notAvailable"

  - `controls.overrideHealth` (boolean)
    Whether health status is overridden

  - `controls.owner` (object)
    Represents a user within a Hyperproof organization.
    Example: {"id":"d2363cab-5199-11ee-a644-522476618ae8","status":"active","type":"activeUser","userId":"82d7c228-8bcd-11e9-a94b-ab3de8494987","email":"jane.doe@example.com","givenName":"Jane","surname":"Doe","language":"en","locale":"US","timeZone":"America/Los_Angeles","title":"Compliance Manager","lastLogin":"2023-05-12T14:16:27.41766Z","permissions":[]}

  - `controls.owner.id` (string)
    The unique identifier for the user within the organization
    Example: "d2363cab-5199-11ee-a644-522476618ae8"

  - `controls.owner.status` (string)
    The status of the object.
    Enum: same as `status` (6 values)

  - `controls.owner.userId` (string)
    The unique identifier for the user across all Hyperproof organizations
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.owner.type` (string)
    The type of a user's membership within a Hyperproof organization.
    Enum: "activeUser", "deactivatedUser", "contact", "serviceAccount", "deactivatedServiceAccount", "syncServiceAccount", "deactivatedSyncServiceAccount"

  - `controls.owner.email` (string)
    The email address of the user
    Example: "jane.doe@example.com"

  - `controls.owner.givenName` (string)
    The given name of the user
    Example: "Jane"

  - `controls.owner.surname` (string)
    The surname of the user
    Example: "Doe"

  - `controls.owner.language` (string)
    The language preference of the user
    Example: "en"

  - `controls.owner.locale` (string)
    The locale preference of the user
    Example: "US"

  - `controls.owner.timeZone` (string)
    The time zone preference of the user
    Example: "America/Los_Angeles"

  - `controls.owner.title` (string)
    The title of the user
    Example: "Compliance Manager"

  - `controls.owner.profilePhotoName` (string)
    The file name of the user's profile photo

  - `controls.owner.identityProviders` (array)
    The list of identity providers for the user. Only populated when expanded

  - `controls.owner.lastLogin` (string)
    The date and time of the user's last login (ISO-8601 format)
    Example: "2023-05-12T14:16:27.41766Z"

  - `controls.owner.externalUserLinks` (array)
    External user links associated with the user
    Example: [{"id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","orgId":"d2363cab-5199-11ee-a644-522476618ae8","userId":"82d7c228-8bcd-11e9-a94b-ab3de8494987","orgUserId":"f4e5d6c7-8901-23ab-cdef-4567890abcde","source":"jira","resource":"https://jira.hyperproof.us","externalUserId":"ext-user-1","userUpdatedOn":"2023-05-12T14:16:27.41766Z","givenName":"Jane","surname":"Doe","status":"active"}]

  - `controls.owner.externalUserLinks.id` (string)
    The unique identifier of the external user link
    Example: "a1b2c3d4-5678-90ab-cdef-1234567890ab"

  - `controls.owner.externalUserLinks.orgId` (string)
    The unique identifier of the organization the link belongs to
    Example: "d2363cab-5199-11ee-a644-522476618ae8"

  - `controls.owner.externalUserLinks.userId` (string)
    The unique identifier of the user the link belongs to
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.owner.externalUserLinks.orgUserId` (string)
    The unique identifier of the organization user the link belongs to
    Example: "f4e5d6c7-8901-23ab-cdef-4567890abcde"

  - `controls.owner.externalUserLinks.source` (string)
    The name of the external source
    Example: "jira"

  - `controls.owner.externalUserLinks.resource` (string)
    The resource within the external source (e.g. a specific Jira Server instance)
    Example: "https://jira.hyperproof.us"

  - `controls.owner.externalUserLinks.externalUserId` (string)
    The unique identifier of the external user in the external source
    Example: "ext-user-1"

  - `controls.owner.externalUserLinks.userUpdatedOn` (string)
    The date and time the user link was last updated (ISO-8601 format)
    Example: "2023-05-12T14:16:27.41766Z"

  - `controls.owner.externalUserLinks.givenName` (string)
    The given name of the external user
    Example: "Jane"

  - `controls.owner.externalUserLinks.surname` (string)
    The surname of the external user
    Example: "Doe"

  - `controls.owner.externalUserLinks.status` (string)
    The status of the object.
    Enum: same as `status` (6 values)

  - `controls.owner.permissions` (array)
    The permissions granted to the user in the organization
    Example: []

  - `controls.owner.organizationRoleId` (string)
    The organization role identifier for the user. Only populated when expanded

  - `controls.owner.systemUseNotificationAcceptedOn` (string)
    The date and time the user accepted the system use notification (ISO-8601 format)

  - `controls.groupId` (string)
    The unique identifier of the group assigned to the control

  - `controls.customFields` (array)
    Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]

  - `controls.status` (string)
    The status of the object.
    Enum: same as `status` (6 values)

  - `controls.createdBy` (string)
    The unique identifier of the user who created the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.createdOn` (string)
    The date the control was created (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `controls.updatedBy` (string)
    The unique identifier of the user who last updated the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.updatedOn` (string)
    The date the control was updated (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `controls.permissions` (array)
    List of permissions the API user has on the control
    Example: []

  - `controls._isPartialData` (boolean)
    This is true when the user does not have read permissions on the control

  - `controls.teamName` (string)
    This field is deprecated and will be removed in a future version. Use scopeName instead

  - `labels` (array)
    The labels linked to the request. Included when the expand query contains 'labels'
    Example: [{"id":"d88d505d-5199-11ee-a644-522476618ae8","orgId":"ce83e3cd-5199-11ee-a644-522476618ae8","name":"Acceptable use of assets","description":"List of acceptable uses of assets by company employees.","freshnessPolicy":"manual","freshForDuration":"PT720H","freshness":"fresh","freshAsOfDate":"2025-01-12T18:26:10.00.5365Z","freshAsOfNote":"Initial freshness set","expiration":"2025-02-11T18:26:10.005365Z","createdBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","createdOn":"2025-01-12T18:26:10.005365Z","updatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","updatedOn":"2025-01-12T18:26:10.005365Z","status":"active","permissions":[]}]

  - `labels.id` (string)
    The unique identifier of the label.
    Example: "d88d505d-5199-11ee-a644-522476618ae8"

  - `labels.orgId` (string)
    The unique identifier for the organization the label belongs to.
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `labels.name` (string)
    The name of the label.
    Example: "Acceptable use of assets"

  - `labels.description` (string)
    The description of the label.
    Example: "List of acceptable uses of assets by company employees."

  - `labels.freshnessPolicy` (string)
    The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
    Enum: same as `controls.freshnessPolicy` (2 values)

  - `labels.freshForDuration` (string)
    The duration after which label becomes stale.
    Example: "PT720H"

  - `labels.freshness` (string)
    The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.
    Enum: same as `controls.freshness` (4 values)

  - `labels.freshAsOfDate` (string)
    The date when the label was last marked 'fresh' (ISO-8601 format).
    Example: "2025-01-12T18:26:10.00.5365Z"

  - `labels.freshAsOfNote` (string)
    The note populated when the label was marked 'fresh'.
    Example: "Initial freshness set"

  - `labels.createdBy` (string)
    The unique identifier of the user who created the label.
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `labels.createdOn` (string)
    The date and time the label was created (ISO-8601 format).
    Example: "2025-01-12T18:26:10.005365Z"

  - `labels.updatedBy` (string)
    The unique identifier of the user who last updated the label.
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `labels.updatedOn` (string)
    The date and time the label was last updated (ISO-8601 format).
    Example: "2025-01-12T18:26:10.005365Z"

  - `labels.customFields` (array)
    The custom fields for the label.

  - `labels.status` (string)
    The status of the object.
    Enum: same as `status` (6 values)

  - `labels.permissions` (array)
    The list of permissions for the label.
    Example: []

  - `labels._isPartialData` (boolean)
    This is true when the user does not have read permissions on the label.

  - `proof` (array)
    The proof linked to the request. Included when the expand query contains 'proof'
    Example: [{"id":"4eb909de-51af-11ee-a644-522476618ae8","orgId":"ce83e3cd-5199-11ee-a644-522476618ae8","filename":"access-control-policy.pdf","nameOverride":"Access Control Policy","contentType":"application/pdf","fileExtension":"pdf","size":102400,"version":0,"source":"localComputer","ownedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","isPrivate":false,"uploadedOn":"2024-10-01 08:00:00+00:00","objectId":"d4e5f6a7-b8c9-0123-abcd-ef4567890123","objectType":"request","proofLinkId":"f1a2b3c4-d5e6-7890-abcd-ef1234567890","proofLinkCreatedOn":"2024-10-02 09:00:00+00:00","proofLinkCreatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","proofLinkStatus":"active","status":"active","createdBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","createdOn":"2024-10-01 08:00:00+00:00","updatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","updatedOn":"2024-10-01 08:00:00+00:00"}]

  - `proof.id` (string, required)
    The unique identifier for the proof item
    Example: "4eb909de-51af-11ee-a644-522476618ae8"

  - `proof.orgId` (string, required)
    The unique identifier of the organization
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `proof.filename` (string, required)
    Name of the uploaded file
    Example: "access-control-policy.pdf"

  - `proof.nameOverride` (string)
    Name of the proof item as set by the user
    Example: "Access Control Policy"

  - `proof.contentType` (string, required)
    MIME type of the file (e.g., text/plain)
    Example: "application/pdf"

  - `proof.fileExtension` (string)
    File extension (e.g., txt)
    Example: "pdf"

  - `proof.size` (integer, required)
    File size in bytes
    Example: 102400

  - `proof.version` (integer)
    Version of the proof item

  - `proof.source` (string)
    Source of the file (e.g., localComputer)
    Example: "localComputer"

  - `proof.sourceVersion` (integer)
    The version of the proof maintained by the source system

  - `proof.ownedBy` (string)
    The unique identifier of the user who owns the proof item
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `proof.isPrivate` (boolean)
    Whether the proof item is private

  - `proof.uploadedOn` (string)
    The date the proof was uploaded (ISO-8601 format)
    Example: "2024-10-01 08:00:00+00:00"

  - `proof.objectId` (string, required)
    The unique identifier of the object this proof is linked to
    Example: "d4e5f6a7-b8c9-0123-abcd-ef4567890123"

  - `proof.objectType` (string, required)
    The type of the object.
    Enum: same as `parentType` (23 values)

  - `proof.proofLinkId` (string)
    The unique identifier of the proof link
    Example: "f1a2b3c4-d5e6-7890-abcd-ef1234567890"

  - `proof.proofLinkCreatedOn` (string)
    The date the proof link was created (ISO-8601 format)
    Example: "2024-10-02 09:00:00+00:00"

  - `proof.proofLinkCreatedBy` (string)
    The unique identifier of the user who created the proof link
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `proof.proofLinkStatus` (string)
    The status of the object.
    Enum: same as `status` (6 values)

  - `proof.status` (string, required)
    The status of the object.
    Enum: same as `status` (6 values)

  - `proof.createdBy` (string)
    The unique identifier of the user who created the proof item
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `proof.createdOn` (string, required)
    The date the proof was created (ISO-8601 format)
    Example: "2024-10-01 08:00:00+00:00"

  - `proof.updatedBy` (string)
    The unique identifier of the user who last updated the proof item
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `proof.updatedOn` (string, required)
    The date the proof was last updated (ISO-8601 format)
    Example: "2024-10-01 08:00:00+00:00"


## Response 401 fields

## Response 403 fields