Document upload

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

You submit one or more file URLs to the bulk upload endpoint.
Nectar queues each file for processing.
A job ID is returned that you can poll for status.
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. Optionally pin every document in the batch to a site and/or utility account, and pass free-text notes as background context for processing. Limits: each document is at most 25MB; PDF page limit is 800. Use v2.2 for new integrations (v2.1 remains available).

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}",
    "accountId": "{accountId}",
    "notes": "Historical bills for Building A — Q1 2025"
  }'

import requests

response = requests.post(
    f"https://external.nectarclimate.com/v2.2/job/company/{company_id}/bulk",
    headers={
        "X-API-Key": "YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
        "documents": [
            "https://your-storage.com/bills/jan-2025-electric.pdf",
            "https://your-storage.com/bills/feb-2025-electric.pdf",
        ],
        "siteId": site_id,
        "accountId": account_id,
        "notes": "Historical bills for Building A — Q1 2025",
    },
)
jobs = response.json()

Request fields

Field	Type	Required	Description
`documents`	Array of strings	Yes	HTTPS URLs where Nectar can download each file
`siteId`	UUID	No	Pin every document in the job to this site instead of best-effort auto-matching
`accountId`	UUID	No	Pin every document in the job to this utility account
`notes`	String	No	Free-text context shared with document processing

Upload a single file

You can also upload a single file directly as a form submission. The same 25MB / 800-page limits apply. Optional siteId, accountId, and notes work the same as bulk upload.

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}' \
  -F 'accountId={accountId}' \
  -F 'notes=Compliance upload for Building A'

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'

response = requests.get(
    f"https://external.nectarclimate.com/v2.2/job/{job_id}",
    headers={"X-API-Key": "YOUR_SECRET_KEY"},
)
job = response.json()
print(job["status"])

Job status values

Status	Description
`PENDING`	Job is queued or in progress
`COMPLETED`	Processing finished successfully
`FAILED`	Processing failed — email [email protected]

When a job completes, the response includes additional fields:

Field	Type	Description
`parsedDocumentIds`	Array	IDs of successfully processed documents
`duplicateDocumentIds`	Array	IDs of documents identified as duplicates
`duplicates`	Integer	Count of duplicate documents
`nonUtilityDocumentIds`	Array	IDs of documents that are not utility bills
`terminationReason`	String	Reason 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

Format	Extension	Notes
PDF	`.pdf`	Most common format; supports multi-page documents
PNG	`.png`	Image of a utility bill
JPG	`.jpg`, `.jpeg`	Image 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 and/or accountId when you need bills allocated to a known site or account — recommended for compliance-sensitive uploads.
Use notes for background context (billing period, source, special instructions).
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

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

How document upload works

Upload documents

Request fields

Upload a single file

Check job status

Job status values

List jobs for a company

Supported file formats

Tips

Next steps

Webhooks

Pagination

Data model

​How document upload works

​Upload documents

​Request fields

​Upload a single file

​Check job status

​Job status values

​List jobs for a company

​Supported file formats

​Tips

​Next steps

Webhooks

Pagination

Data model

How document upload works

Upload documents

Request fields

Upload a single file

Check job status

Job status values

List jobs for a company

Supported file formats

Tips

Next steps