Uploading and Retrieving Proof
The Hyperproof API can be used to upload proof to an organization, control, label, or task. It also supports the retrieval of proof metadata and contents from these locations.
Uploading Proof to an Organization
To upload a proof file to an organization, issue an HTTP multipart form request to the https://api.hyperproof.app/v1/proof endpoint. Include the proof document in the request body using the name proof.
Example
The following curl command uploads a file called InfoSecPolicy.docx to Hyperproof as a proof file:
curl -F "proof=@InfoSecPolicy.docx \-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \https://api.hyperproof.app/v1/proof
NOTE: In the example above, the Authorization header must be updated with an access token retrieved from the https://accounts.hyperproof.app/oauth/token endpoint. For more information on obtaining an access token, see Getting Started.
If successful, the return value is a JSON object containing the metadata for the uploaded proof file:
{
"id": "4b060536-433e-47e9-a9a5-28d98695750c"
"filename": "InfoSecPolicy.docx",
"version": 0,
"size:": 123456,
...
"createdBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"createdOn": "2024-02-24T12:01:57+0000",
"updatedBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"updatedOn": "2024-02-24T12:01:57+0000",
}To identify the user who owns the uploaded proof, use the optional hp-proof-owned-by field.
If the field is specified, provide the ID of the owner as the value.
Example
curl -F "proof=@InfoSecPolicy.docx" \
-F "hp-proof-owned-by=OWNER_USER_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof
Uploading a New Proof Version
Upload a new version of a proof item by issuing an HTTP multipart form request to the https://api.hyperproof.app/v1/proof/{proofId}/versions endpoint.
Example
The following curl command uploads a file called InfoSecPolicyV7.docx as a new proof version:
curl -F "proof=@InfoSecPolicyV7.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof/YOUR_PROOF_ID/versions
If successful, the return value is a JSON object containing the metadata for the uploaded proof file. The version number is one greater than the previous highest version number.
{
"id": "4b060536-433e-47e9-a9a5-28d98695750c"
"filename": "InfoSecPolicyV7.docx",
"version": 6,
"size:": 123789,
...
"createdBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"createdOn": "2024-02-24T12:01:57+0000",
"updatedBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"updatedOn": "2024-02-25T14:08:13+0000"
}Uploading Proof to a Control, Label or Task
The Hyperproof API provides REST endpoints that allow you to upload a proof file and immediately link it to a control, label, or task. There is one such endpoint per object type, each of which uses the following format:
https://api.hyperproof.app/v1/{objectType}s/{objectId}/proofFor example, to upload a proof file to a control, issue an HTTP multipart form request to the https://api.hyperproof.app/v1/controls/{controlId}/proof endpoint.
Example
The following curl command uploads a document called PrivacyPolicy.docx to Hyperproof and links it to a control:
curl -F "proof=@PrivacyPolicy.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/controls/YOUR_CONTROL_ID/proof
Retrieving Proof Metadata from an Organization
To retrieve the metadata for proof items in an organization, issue an HTTP GET request to the https://api.hyperproof.app/v1/proof endpoint.
The proof REST API uses pagination to handle large numbers of proof files for an organization. A limit query string parameter is used in the initial GET request to indicate the maximum number of proof items to return. If unspecified, a default limit value of 25 is used. If more than limit proof items exist, an offsetToken value is returned in the response that allows the next page of records to be retrieved.
Example
Specify a limit value in the initial request to retrieve proof metadata, unless you want the default value:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof?limit=100
If successful, the return value is a JSON object containing one page of data, along with an offset token.
{
"data": [
{
"filename": "InfoSecPolicy.docx",
"version": 0,
"size:": 123456,
...
"createdBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"createdOn": "2024-02-24T12:01:57+0000",
"updatedBy": "cc58458f-dbda-4273-bbc9-91dd76868840",
"updatedOn": "2024-02-24T12:01:57+0000",
},
...
],
"offsetToken": "eyJvcmdJZCI6IjIxN..."
}When offsetToken is returned in the response, the next page of data can be retrieved by providing that value in the offset query string parameter of a subsequent request to the same endpoint:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof?offset=eyJvcmdJZCI6IjIxN...
Proof Metadata Order
By default proof metadata is ordered by the uploadedOn property, with the most recently uploaded proof at the top of the list. To specify some other sort order, use the sortBy and sortDirection query string parameters.
Valid sortBy values are: createdBy, createdOn, filename, and uploadedOn (the default). Note that the uploadedOn property of a proof is updated when a new version is uploaded, but the createdOn property is fixed.
The sortDirection parameter can be set to either asc for ascending or desc for descending (the default).
Other Query String Parameters
To retrieve the proof owned by the authorized user, set the ownedByMe query string parameter to true.
Use the search query string parameter to limit the result to those proof items with a filename matching the search value.
Example
The example below retrieves the proof owned by the authorized user. The proof is ordered by filename property, ascending. Because no limit query string parameter is provided, the default page size of 25 will be used.
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof?sortBy=filename&sortDirection=asc&ownedByMe=true
Retrieving Proof Metadata from a Control, Label, or Task
The https://api.hyperproof.app/v1/proof endpoint is also used to retrieve the proof metadata for proof linked to a control, label, or task. The objectType and objectId query string parameters filter the returned proof metadata to proof linked to a specific object instance.
Example
The following curl command retrieves the the first page of proof metadata for all proof items linked to a control:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof?objectType=control&objectId=YOUR_CONTROL_ID&limit=100
If successful, the return value is a JSON object containing a page of data, along with an offset token.
Retrieving Proof Contents
The contents of individual proof files can be downloaded from Hyperproof using the https://api.hyperproof.app/v1/proof/{proofId}/contents endpoint. The contents of the proof file are returned in the response body, and the filename is returned in the content-disposition response header.
Example
Proof files can be downloaded with a curl command like this:
curl -O --remote-header-name \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof/YOUR_PROOF_ID/contents
If successful, this curl command downloads the file contents and saves it to the local computer using the filename specified in the content-disposition response header.
To retrieve the contents for a specific version of a proof item, use the version query string parameter:
curl -O --remote-header-name \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.hyperproof.app/v1/proof/YOUR_PROOF_ID/contents?version=123