Upload documents to BILL

You can upload a document to your BILL Inbox with /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 /UploadAttachment.json request.

Field nameDescription
idBILL ID of the object to attach the document. You attach the document to different BILL objects - bill, invoice, vendor, customer, vendor credits, bill payments, invoice payments, or chart of accounts.

When you want to upload the document to the BILL Inbox, id is not required.
fileEntire path of the file path with file extension. This field is required.
fileNameFile name. You must include the file extension of the file. This field is required.

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-sandbox.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-sandbox.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 /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 /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.