Skip to main content
In addition to automatic bill collection via connections, you can upload documents directly through the API. This is useful for historical bills, one-off documents, or bills from utilities that don’t have online portals.

​
How document upload works

  1. You submit one or more file URLs to the bulk upload endpoint.
  2. Nectar queues each file for processing.
  3. A job ID is returned that you can poll for status.
  4. When processing completes, documents and usage data appear in the API like any other bill.

​
Upload documents

Use the bulk upload endpoint to submit files for a company. Provide a documents array of publicly accessible HTTPS URLs and an optional siteId to assign the documents to a site. 
curl -X POST 'https://external.nectarclimate.com/v2.2/job/company/{companyId}/bulk' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "documents": [
      "https://your-storage.com/bills/jan-2025-electric.pdf",
      "https://your-storage.com/bills/feb-2025-electric.pdf"
    ],
    "siteId": "{siteId}"
  }'

​
Request fields

FieldTypeRequiredDescription
documentsArray of stringsYesHTTPS URLs where Nectar can download each file
siteIdUUIDNoSite to assign the uploaded documents to

​
Upload a single file

You can also upload a single file directly as a form submission. 
curl -X POST 'https://external.nectarclimate.com/v2.2/job/company/{companyId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -F 'document=@/path/to/bill.pdf' \
  -F 'siteId={siteId}'

​
Check job status

After uploading, poll the job detail endpoint to check processing status. 
curl -X GET 'https://external.nectarclimate.com/v2.2/job/{jobId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

​
Job status values

StatusDescription
PENDINGJob is queued or in progress
COMPLETEDProcessing finished successfully
FAILEDProcessing failed — contact support
When a job completes, the response includes additional fields:
FieldTypeDescription
parsedDocumentIdsArrayIDs of successfully processed documents
duplicateDocumentIdsArrayIDs of documents identified as duplicates
duplicatesIntegerCount of duplicate documents
nonUtilityDocumentIdsArrayIDs of documents that are not utility bills
terminationReasonStringReason for termination (if applicable)

​
List jobs for a company

Retrieve all upload jobs for a company to monitor bulk processing progress. 
curl -X GET 'https://external.nectarclimate.com/v2.2/job/company/{companyId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

​
Supported file formats

FormatExtensionNotes
PDF.pdfMost common format; supports multi-page documents
PNG.pngImage of a utility bill
JPG.jpg, .jpegImage of a utility bill

​
Tips

  • All URLs in the documents array must start with https://. If your files are in a private S3 bucket, generate a pre-signed URL.
  • Include siteId to help Nectar assign the extracted data to the correct location.
  • Processing typically completes within a few minutes per document.
  • Once processed, the documents appear in the standard /document/ endpoints and trigger document.created.v2 webhooks if configured.

​
Next steps

Webhooks

Get notified when documents finish processing

Pagination

Iterate through document lists

Data model

Understand how documents relate to usage data