Skip to main content
Version: 2.0.0

UploadFile

UploadFile

Use this endpoint to upload a PDF, JPG, or PNG file to TaxBandits. The response gives you a FileId that you can pass to other endpoints, such as WhCertificate/Extract.

The file doesn't pass through the TaxBandits API. You upload it straight to secure storage (Amazon S3), where it's encrypted with your account's encryption key.

How It Works​

  • 1. Get an upload link — Call Utility/UploadFile with the type of the file you'll upload. The response returns a FileId, a PreSignedUrl, and PreSignedFields.
  • 2. Upload the file to S3 — Before ExpiresAt, send the file to the PreSignedUrl with the PreSignedFields and your encryption fields. See Upload the File to S3.
  • 3. Use the FileId — After the upload succeeds, pass the FileId to an endpoint that accepts it, such as WhCertificate/Extract.
RequirementValue
Supported formatsPDF, JPG, PNG
Maximum file size5 MB
Upload link expiry1 minute after it's created
EncryptionAES-256, with your account's encryption key
POST Utility/UploadFile 

Request Headers

HeaderValue
Authorization<AccessToken>
Content-Typeapplication/json

Request Body

FieldTypeDescription
ContentTypeStringType of the file you'll upload.
Allowed values

"application/pdf", "image/jpeg", "image/png"

Note: The file you send to S3 must be of this type.

Response Body

FieldTypeDescription
FileIdGUIDUnique ID of the file. After the upload is complete, pass it to an endpoint that accepts a FileId, such as WhCertificate/Extract .
PreSignedUrlStringS3 address to send the file to.
PreSignedFieldsObjectForm fields to send, unchanged, with the file to S3.
   keyStringStorage path of the file.
Format: <Filepath>.<ext> (ext is pdf, jpg, or png)
   policyStringBase64-encoded upload rules: expiry, file type, size limit, and encryption.
   X-Amz-AlgorithmStringSigning algorithm. Always AWS4-HMAC-SHA256.
   X-Amz-CredentialStringCredential scope used to sign the upload.
   X-Amz-DateStringDate and time (UTC) the upload was signed.
   X-Amz-SignatureStringSignature that protects the upload fields from changes.
   Content-TypeStringFile type. Same as the ContentType in the request.
ExpiresAtStringDate and time the upload link expires.
Format: YYYY-MM-DD HH:MM:SS ±HH:MM
ErrorsObject []Detailed error information.
   IdStringValidation error ID.
   NameStringName of the validation error.
   MessageStringDescription of the validation error.

Upload the File to S3​

Send a POST request to the PreSignedUrl with a multipart/form-data body that has the fields below. Don't send the Authorization header to S3.

S3 Form Fields

FieldTypeDescription
All PreSignedFields entriesStringEach name and value exactly as returned: key, policy, X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Signature, and Content-Type.
x-amz-server-side-encryption-customer-algorithmStringEncryption algorithm. Always AES256.
x-amz-server-side-encryption-customer-keyStringYour account's encryption key: a 256-bit key, Base64-encoded.
x-amz-server-side-encryption-customer-key-MD5StringMD5 hash of your encryption key, Base64-encoded. See Calculate the Key MD5.
fileFileThe file to upload. Must be the last field.
  • Send the PreSignedFields exactly as you received them. Don't rename or change any of them.
  • Put the file field last. S3 ignores any field sent after it.
  • Complete the upload before ExpiresAt. If the link expires, call Utility/UploadFile again to get a new one.
  • Use the FileId only after S3 confirms the upload.

Calculate the Key MD5​

The x-amz-server-side-encryption-customer-key-MD5 field is the MD5 hash of your encryption key. Decode the key from Base64 first, hash the decoded bytes, then Base64-encode the hash.

echo -n '<<Encryption Key>>' | base64 -d | openssl md5 -binary | base64

Check your code: run it with the sample key below and compare the result. This key is only for testing.

ValueSample
Encryption keyMDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=
Expected key MD5hRasmdxgYDKV3nvbahU1MA==

If you get t52DDCIm7WL8PC2PMFZOiw==, you hashed the Base64 text instead of the decoded key bytes.

Sample Code​

Each sample does all three steps: it gets the upload link from Utility/UploadFile, calculates the key MD5, and posts the file to S3. Replace the values in <<...>> with your own. In the cURL sample, copy the PreSignedUrl and PreSignedFields values from the step 1 response into step 3.

# Step 1: Get the upload link
curl --location '<<TaxBandits API URL>>/v2.0.0/Utility/UploadFile' \
--header 'Authorization: <<Access Token>>' \
--header 'Content-Type: application/json' \
--data '{ "ContentType": "application/pdf" }'

# Step 2: Calculate the key MD5
ENCRYPTION_KEY='<<Encryption Key>>'
KEY_MD5=$(echo -n "$ENCRYPTION_KEY" | base64 -d | openssl md5 -binary | base64)

# Step 3: Post the file to S3. Copy PreSignedUrl and each PreSignedFields value from the step 1 response.
curl --location '<<PreSignedUrl>>' \
--form-string 'Content-Type=application/pdf' \
--form-string 'X-Amz-Algorithm=AWS4-HMAC-SHA256' \
--form-string 'X-Amz-Credential=<<X-Amz-Credential>>' \
--form-string 'X-Amz-Date=<<X-Amz-Date>>' \
--form-string 'X-Amz-Signature=<<X-Amz-Signature>>' \
--form-string 'key=<<key>>' \
--form-string 'policy=<<policy>>' \
--form-string 'x-amz-server-side-encryption-customer-algorithm=AES256' \
--form-string "x-amz-server-side-encryption-customer-key=$ENCRYPTION_KEY" \
--form-string "x-amz-server-side-encryption-customer-key-MD5=$KEY_MD5" \
--form 'file=@"<<File Path>>";type=application/pdf' \
--write-out 'S3 status: %{http_code}\n'

Common Errors​

Utility/UploadFile​

Status / ErrorDescription
400 – C00-000409ContentType is missing, or isn't application/pdf, image/jpeg, or image/png.
401 – UnauthorizedThe access token is missing, invalid, or expired.

S3 Upload​

Status / ErrorDescription
403 – Policy expiredThe upload link expired. Call Utility/UploadFile again.
400 – EntityTooLargeThe file is larger than 5 MB.
400 – EntityTooSmallThe file is empty.
403 – Invalid according to PolicyA field is missing or changed, Content-Type differs from the returned value, or the encryption key or its MD5 is wrong.
400 – InvalidArgumentThe encryption key isn't a valid 256-bit Base64 key, or doesn't match the key MD5 you sent.
Request Json
SampleDescriptionAction
Sample 1
Requests a pre-signed URL to upload a PDF file.
Sample 1
{
"ContentType": "application/pdf"
}
Response Json
SampleDescriptionAction
200
Success Response - This is a sample response for successful API requests.
401
Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.
Response: 200
{
"FileId": "3f1c2a9e-7b4d-4c1a-9e2f-1a2b3c4d5e6f",
"PreSignedUrl": "https://<bucket>.s3.us-east-1.amazonaws.com",
"PreSignedFields": {
"Content-Type": "application/pdf",
"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
"X-Amz-Credential": "<Credential>",
"X-Amz-Date": "<Date>",
"X-Amz-Signature": "<Signature>",
"key": "<FileName>",
"policy": "<Base64Policy>"
},
"ExpiresAt": "2026-07-07 10:25:31 -04:00",
"Errors": null
}