Upload documents

You can upload a document to your BILL Inbox with /v2/UploadAttachment.json. You can also attach the document to different BILL objects - bill, invoice, vendor, customer, vendor credits, bill payments, invoice payments, or chart of accounts.

Request parameters

There are three request parameters in your /v2/UploadAttachment.json request.

cURL API request

In your request, file and fileName is required.

• Set file as the file to be uploaded. Include the entire file path with file extension.
• Set fileName as the file name including the file extension.
• You can set id as the BILL ID of the object to attach the document.

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/UploadAttachment.json' \
--header 'accept: application/json' \
--header 'content-type: multipart/form-data' \
--form 'devKey={developer_key}' \
--form 'sessionId={session_id}' \
--form 'file=@"{filepath}"' \
--form 'data="{\"id\":\"{object_id}\", \"fileName\":\"{file_name}\"}"'

HTTP API request

In your request, file, fileName, and Content-Type is required.

• Set file as the file to be uploaded. Include the entire file path with file extension. Do not use Base64 encoding for the file in your HTTP API request.
• Set fileName as the file name including the file extension.
• Set Content-Type as the document type. For example, for a PNG image, set Content-Type as image/png. For a PDF, set Content-Type as application/pdf.
• You can set id as the BILL ID of the object to attach the document.

POST /api/v2/UploadAttachment.json HTTP/1.1
Host: api-stage.bill.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="devKey"

{developer_key}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="sessionId"

{session_id}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="{file_name}"
Content-Type: image/png

{file_binary_information}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="data"

{"id":"{object_id}", "fileName":"{file_name}"}
----WebKitFormBoundary7MA4YWxkTrZu0gW

Response

In the response, a BILL-generated documentUploadId is generated. The value begins with 0du. You can use this value to download the document with /v2/GetDocumentPages.json.

{
   "response_status" : 0,
   "response_message" : "Success",
   "response_data" : {
       "documentUploadedId" : "{object_id}" 
   }
}

If you do not set an id in your request, the document is uploaded to your BILL Inbox.

📘

NOTE

In the production environment, when a document is uploaded to the BILL Inbox, it is automatically processed and relevant information is prefilled when you create a bill. See Bills detected by Intelligent Virtual Assistant (IVA) in the BILL Help Center for more information.

File requirements

Uploading documents with /v2/UploadAttachment.json has a set of requirements.

• The user that is uploading the document must have at least one of the following permissions: Use Inbox, View and Manage Company Info, or Approve Bills/Vendor Credits.
• BILL supports popular file formats, such as Microsoft Word, Excel, PowerPoint, Adobe PDF, TXT, PNG, JPG, and GIF.
• The maximum file size is 20 MB.
• The file extension must match the extension in your API request.
• A document can be associated with only one BILL object.
• If the BILL object ID is invalid, an error message is returned and the document is not uploaded.

See Supported file formats in the BILL Help Center for more information.