Document APIs

You can manage documents through the following APIs.

Get Documents
Create a Document

Get Documents

Use this endpoint to get information about a selected set of documents linked to requisitions.

HTTP Request

GET /api/v3/documents

Query Parameters

Key	Required	Description
`projectTemplateId`	yes	Limits response to documents linked to requisitions in this project templateInternal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
`requisitionIdentifier`	yes	Limits response to documents linked to the requisition with this Requisition Identifier
`folderName`	no	Limits response to documents in this folder
`startDate`	yes	Limits response to documents created on or after this date
`endDate`	yes	Limits response to documents created on or before this date
`page`	no	Page number being requestedDefaults to page 1 if not supplied
`perPage`	no	Number of documents to return per pageMaximum of 5000 and defaults to 5000 if not supplied

Response

This endpoint can return the following responses:

Response code	Response body
200 to indicate success	JSON describing the requested documents (see below)
401 to indicate an authentication error
404 to indicate an error with the request	The validation errors found For example: "ProjectRequisitionTemplateAssociation Not Found" or "Requisition Not Found"

Response Body

{
  "documents": [
    {
    "id": 3456789,
    "name": "example.pdf",
    "requisitionId": 1123456,
    "requisitionIdentifier": "REQ-1",
    "downloadLink": "https://...",
    "createdAt": "2021-01-25T22:06:21.000Z",
    "uploadLink": null
    },
    ...
  ],
  "meta":
    {
    "currentPage": 3,
    "perPage": 100,
    "totalEntries": 1234
    }
}

Field name	Description
`documents[].id`	The system-provided internal identifier for the document; do not use
`documents[].name`	The document's name
`documents[].requisitionId`	The system-provided internal identifier for the document's requisition; do not use
`documents[].requisitionIdentifier`	The Requisition Identifier of the document's requisition
`documents[].downloadLink`	A temporary URL from which you can download the document; pass the same bearer token in that download request
`documents[].createdAt`	When the document was created
`documents[].uploadLink`	Always `null` for this API When this body is returned from the API used to create requisitions (see below), this is a temporary URL to which you can upload the document; pass the same bearer token in that download request
`meta.currentPage`	The number of documents per page (the same as the value expressed in the `page` query parameter)
`meta.perPage`	The number of documents per page (the same as the value expressed in the `perPage` query parameter)
`meta.totalEntries`	The total number of documents that satisfy the query parameters (not the number of documents in this response)

Create a Document

Use this API to create and upload a new document.

Request

POST /api/v3/documents

Request Body

{
  "document":
    {
    "projectTemplateId": int,
    "requisitionIdentifier": "string",
    "folderName": "Some folder name",
    "fileName": "example.pdf",
    "fileContent": "the base64-encoded contents of the file",
    "returnUploadLink": true
    }
}

Field name	Required	Description
`projectTemplateId`	yes	Internal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
`requisitionIdentifier`	yes	The Requisition Identifier of the requisition this document will be linked to
`folderName`	yes	Folder document will be added to
`fileName`	yes	Name of document to be added
`fileContent`	optional	Base64 content of file (only used if not requesting an upload link)
`returnUploadLink`	optional	Used to request a link to upload the file to S3 (only used if not sending fileContent) The upload file's name must match `fileName` .

Response

Response code	Response body
201 Indicating the resource was successfully created	As described above under Get Documents
401 Indicating an authentication error
422 Indicating an error with the request contents	The validation error(s) foundFor example: "fileName required" or "Folder Name invalid or not found"