Table of Contents
Summary
Whistic's API allows you to programmatically upload documents to both Issue Management and the Vendor Document Repository. This feature streamlines document management workflows by enabling automated uploads directly through API calls, eliminating the need for manual file uploads through the Whistic interface.
Important Notes:
- Documents are automatically scanned for viruses during upload
- Currently, bulk uploading is not supported
- Only specific document types and formats are supported
- Each upload follows a two-step process: file creation and content upload
🔐 Before You Begin
Requirements:
- Valid Whistic API key
- Access to the Vendor Document Repository or Issue Management (depending on your use case)
- Documents must be in supported formats (PDF recommended, other supported types include: .docx, .xlsx)
- Files cannot be encrypted or password protected
API Documentation:
- Review our complete API documentation on our Swagger page
- Ensure you have the correct base URL and authentication headers configured
Supported Upload Destinations:
- Vendor Document Repository - For storing vendor-related documents and compliance materials
- Issue Management - For attaching supporting documents to specific issues
🚀 Step-by-Step Upload Process
Step 1: Initiate File Upload (POST Request)
Start by creating a file record with basic metadata. This generates an upload URL for the actual file content.
Request Format:
POST /api/vendors/{vendor-id}/documents
Content-Type: application/json
{
"file_name": "your-document-name.pdf"
}What You'll Receive:
- A unique HREF
- Headers needed:
- "x-amz-server-side-encryption": "AES256",
- "Content-Type": "application/octet-stream"
Example Response:
{
"upload": {
"href": "https://whistic-uploaded-documents-testenv.s3.amazonaws.com/NjM5Mj...................",
"title": "Upload document content",
"type": "PUT",
"headers": {
"x-amz-server-side-encryption": "AES256",
"Content-Type": "application/octet-stream"
}
},
}Step 2: Upload File Content (PUT Request)
Use the upload HREF from Step 1 to upload your actual file content as binary data.
Request Configuration:
- Method: PUT
- URL: Use the 'upload.href' from the response from Step 1
- Content-Type: Set to binary or the appropriate MIME type
- Body: Include your file as binary data (not base64 encoded)
In Postman or Similar Tools for Testing:
- Select PUT method
- Enter the upload URL
- In the Body tab, select "binary"
- Choose your file directly from the file picker
- Send the request
Step 3: Verify Upload Success
Successful Upload Indicators:
- HTTP 200 status code
- Empty response body (this is normal)
- Document appears in the appropriate Whistic repository
Where to Check:
- Navigate to the vendor's Document Repository in Whistic
- Verify the file is visible and downloadable
- Check that file metadata matches your upload
Here is a sample of the Vendor Document Repository (without any documents)
📋 Understanding the Response
POST Response (Step 1)
The initial POST request returns metadata and upload instructions:
- upload_url: Temporary URL for file upload (expires after a set time)
- file_id: Unique identifier for tracking
- expires_at: When the upload URL expires
PUT Response (Step 2)
The file upload PUT request typically returns:
- HTTP 200: Successful upload
- Empty body: Normal and expected
- File processing: Begins automatically after upload
🔧 Troubleshooting Common Issues
Upload Failures
File Format Issues:
- Ensure your file is not encrypted or password protected
- Verify the file format is supported (PDF recommended)
- Check that the file size is within acceptable limits
Authentication Problems:
- Verify your API key
- Ensure authentication headers are correctly formatted
- Check that your account has access to the target repository
Upload URL Expired:
- Generate a new upload URL by repeating Step 1
- Complete the upload process within the expiration timeframe
- Upload URLs are temporary and cannot be reused
Common Error Responses
500 Internal Server Error:
- Contact Support@Whistic.com with request details
- Include the file type and size in your support request
Authentication Errors:
- Regenerate your API key if authentication continues to fail
- Verify the API key format and permissions
File Processing Delays:
- Allow 2-5 minutes for virus scanning and processing
- Large files may take longer to appear in the repository
- Contact support if files don't appear after 10 minutes
❓ FAQ
Do I need to encode my file content as base64?
No, when using the binary upload method (recommended), send the file content directly as binary data. Do not base64 encode the file content for the PUT request.
What does a successful upload response look like?
A successful upload returns HTTP 200 status with an empty response body. This is normal - the file will appear in Whistic after processing is complete.
How long does it take for uploaded documents to appear in Whistic?
Most documents appear within 2-5 minutes after a successful upload. This includes time for virus scanning and processing. Larger files may take slightly longer.
Can I upload multiple files at once?
Currently, bulk uploading is not supported. Each file must be uploaded individually using the two-step process. Bulk upload functionality is planned for future enhancement.
What file formats are supported?
PDF files are recommended and fully supported. Other common document formats may work, but testing is recommended for your specific use case.
Why is my file upload timing out or failing?
Common causes include:
- File is encrypted or password protected
- Upload URL has expired
- File format is not supported
- Network connectivity issues during upload
Can I upload files to both Issues and Vendor Document Repository?
Yes, but you'll use different API endpoints for each destination. Check the Swagger documentation for the specific endpoints for each upload type.
What happens if my upload URL expires?
Upload URLs are temporary for security purposes. If expired, simply repeat Step 1 to generate a new upload URL and complete the process.
How do I track the upload progress or status?
After a successful PUT request, monitor the target repository in Whistic. The file will appear once processing is complete. For Issues, check the specific issue's attachments section.
Can I replace or update an uploaded document?
You would need to upload a new version of the document. The API doesn't currently support direct file replacement - this would be handled as a new upload.