Semantik Invoice includes an API to programmatically upload an invoice. This document provides an overview of how to use the Document Upload API.
Note: These instructions use Postman, however the same steps can be adapted for the command line or another API tool.
Prerequisites
You will need:
A Semantik API Key. For steps, refer to developer.ephesoft.net.
A free Postman account.
Overview
The Document Upload API requires three steps to get a document uploaded for Semantik to process.
Request an upload URL.
Upload the invoice to the URL.
Allow Semantik to process the invoice.
Step 1. Request an Upload URL
First, create an Amazon S3 presigned URL to initialize the upload process. The Amazon S3 presigned URL is a URL that allows temporary access to upload your file to Semantik. In this step, you will use the Document Upload API POST endpoint.
To do so, perform the following:
1. In Postman, create a New Request.
2. Set the method to POST and the request URL to "https://api.us.ephesoft.io/v1/documents/uploads"
3. Add the Authorization header to your POST:
a. Click the Headers tab.
b. Set the KEY to "Authorization" and the VALUE to "ApiKey <Your Key Here>"
4. Set the content type to application/json and add the request body:
a. Click the Body tab.
b. Click raw and select JSON from the dropdown.
c. Add the request body to the text field. This requires the following two properties:
fileName: The name of the file you want to upload, including the file extension.type: The document type. This must be set to "invoice".
Example request:
{
"fileName": "sample.jpg",
"type": "invoice"
}
5. Click Send.
The response contains two key pieces of information that you must save:
id— The unique identifier Semantik assigned to the documenturl— The Amazon S3 presigned URL.
6. Copy the url and proceed to the next step.
Step 2. Upload the Invoice to the URL
Next, upload the document using the Amazon S3 presigned URL you just created. For more information on this topic, refer to Amazon's article on Uploading objects using presigned URLs. In this step, you will use the PUT method.
To do so, perform the following:
1. In Postman, create a New Request.
2. Set the method to PUT and the request URL to the Amazon S3 presigned URL you copied from the POST request.
3. Click the Body tab.
4. Change the body type to binary and click Select File.
5. Select your invoice and click OK.
6. Click Send. You should receive a 200 OK HTTP status code.
Note: If you receive a 403 Forbidden error, your S3 presigned URL has likely expired. Go back to step 1 and resend the POST request for a new presigned URL. This URL will expire after 60 seconds.
Step 3. Allow Semantik to Process the Invoice
Once the file has been successfully uploaded, the document is now securely stored in Semantik. In this step, you will allow Semantik to process the invoice using the Document Upload API PATCH endpoint.
To do so, perform the following:
1. In Postman, create a New Request.
2. Set the method to PATCH and the request URL to "https://api.us.ephesoft.io/v1/documents/uploads/:uploadId" where ":uploadId" is the id you saved from the POST request.
3. Add the Authorization header to your PATCH:
a. Click the Headers tab.
b. Set the KEY to "Authorization" and the VALUE to "ApiKey <Your Key Here>"
4. Set the content type to application/json and add the request body:
a. Click the Body tab.
b. Click raw and select JSON from the dropdown.
c. Add the request body to the text field. This should exactly match the example request below.
Example request:
{
"status": "completed"
}
5. Click Send. You should receive a 200 OK HTTP status code. You can now log in to your Semantik dashboard and view the document you uploaded.
Note: If you receive a 400 Bad Request error, the document may exceed the size limit (30 MB), or the file extension may not be a supported file type. Check the response message.
Conclusion
This completes an overview of how to use the Document Upload API.
Related Articles