External systems can now interact with Documents that are stored in AssignmentPro, or create new Documents, via API requests. Regardless of which Document endpoint is being used, there are certain requirements and considerations that need to be taken into account.
The primary key that is used to retrieve Documents with GET requests will be the ID of the Document. Going about discovering the Document ID is outlined for each of the new API subscriptions that are available:
All requests made to Document endpoints will return the same fields as in the below example made against the Employee Document endpoint:
Note that in this example, the content for “document” has been shortened for readability.
Retrieving Documents out of AssignmentPro
When using GET requests to pull Documents out of AssignmentPro, the data for the Documents themselves will always be returned as deflated Base64 encoded strings. In order to be viewed by end users, the target system consuming requested Documents will need to utilize one of many commonly available libraries to handle inflating the Documents.
Pushing Documents into AssignmentPro
When using POST requests to push Documents into AssignmentPro, the API will automatically calculate the Content Length based on the inflated and unencrypted Document length, and this key cannot be edited directly by requests. Documents can be provided in requests as either deflated or inflated Base64 strings, and must be 25MB or less. When virus scanning is turned on in an environment, Documents being pushed into the system will be scanned.
Additionally, the following must be met in order for a POST request to a Document endpoint to succeed:
File Name must have a file extension appended in order to be downloaded and opened from within the application by end users
POST requests will automatically fail when there is no content for “document” provided
Document Type ID is required
Content Type is required
File Name is required
Name is required
A valid relationship to the parent record must be provided. This will vary depending on which Document endpoint a request is being made against, and more details can be found below
Note that the Document Type ID key will function as a lookup, so the plain text Display Value can be requested or provided in requests. For more details around using query string parameters for lookups click here.
Additionally, an API Subscriber must have the proper Data Sensitivity rights to GET Documents with a Document Type that is configured to have restricted access. Similarly, POST requests will fail when the included Document Type is one which the Subscriber does not have rights to.
Subscriptions
Two new API Subscriptions are available that enable management of certain Documents in AssignmentPro. The methods that are supported are different between each of them, and each one grants rights to interact with a specific set of endpoints, which map to different types of Documents in the application.