Submit Job via Bulk Document Upload

curl --request POST \
  --url https://external.nectarclimate.com/v2/job/company/{company_id}/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "documents": [
    "<string>"
  ],
  "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "notes": "<string>"
}
'

import requests

url = "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk"

payload = {
    "documents": ["<string>"],
    "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "notes": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documents: ['<string>'],
    siteId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    accountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    notes: '<string>'
  })
};

fetch('https://external.nectarclimate.com/v2/job/company/{company_id}/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documents' => [
        '<string>'
    ],
    'siteId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'accountId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'notes' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk"

	payload := strings.NewReader("{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://external.nectarclimate.com/v2/job/company/{company_id}/bulk")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://external.nectarclimate.com/v2/job/company/{company_id}/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "PENDING",
  "parsedDocumentIds": [
    "<string>"
  ],
  "duplicates": 123,
  "duplicateDocumentIds": [
    "<string>"
  ],
  "nonUtilityDocumentIds": [
    "<string>"
  ],
  "passwordProtectedDocumentIds": [
    "<string>"
  ],
  "errorDocumentIds": [
    "<string>"
  ],
  "terminationReason": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>"
}

Jobs

Submit Job via Bulk Document Upload

Submit multiple documents using signed S3 URLs for processing as a single job. The company must be active to submit a job. The size limit of each individual document is 25MB, and the page limit for PDF files is 800. Returns a job ID that can be used to track the status of all submitted documents. Use the job status endpoint to monitor processing progress and retrieve document IDs once completed. You can also pin every document in this batch to a specific site or utility account by passing the corresponding siteId and/or accountId. When provided, every parsed bill in the job is allocated to that site/account instead of relying on best-effort auto-matching — recommended for compliance-sensitive uploads to prevent bills from landing on the wrong site. Free-text notes are shared with document processing as background context.

POST

job

company

{company_id}

bulk

Submit Job via Bulk Document Upload

curl --request POST \
  --url https://external.nectarclimate.com/v2/job/company/{company_id}/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "documents": [
    "<string>"
  ],
  "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "notes": "<string>"
}
'

import requests

url = "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk"

payload = {
    "documents": ["<string>"],
    "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "notes": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documents: ['<string>'],
    siteId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    accountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    notes: '<string>'
  })
};

fetch('https://external.nectarclimate.com/v2/job/company/{company_id}/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documents' => [
        '<string>'
    ],
    'siteId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'accountId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'notes' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://external.nectarclimate.com/v2/job/company/{company_id}/bulk"

	payload := strings.NewReader("{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://external.nectarclimate.com/v2/job/company/{company_id}/bulk")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://external.nectarclimate.com/v2/job/company/{company_id}/bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documents\": [\n    \"<string>\"\n  ],\n  \"siteId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"notes\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "PENDING",
  "parsedDocumentIds": [
    "<string>"
  ],
  "duplicates": 123,
  "duplicateDocumentIds": [
    "<string>"
  ],
  "nonUtilityDocumentIds": [
    "<string>"
  ],
  "passwordProtectedDocumentIds": [
    "<string>"
  ],
  "errorDocumentIds": [
    "<string>"
  ],
  "terminationReason": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>"
}

Authorizations

X-API-KEY

string

header

required

Path Parameters

company_id

string<uuid>

required

ID of the company for which to submit jobs.

Body

Serializer for form fields during job bulk submission.

documents

string[]

required

List of presigned URLs for files to be processed by the job.

Minimum string length: 1

siteId

string<uuid> | null

UUID of the site to pin all uploaded documents to. When provided, every parsed bill in this job is allocated to this site instead of relying on best-effort auto-matching.

accountId

string<uuid> | null

UUID of the utility account to pin all uploaded documents to. When provided, every parsed bill in this job is associated with this account (and its parent utility connection) instead of relying on best-effort auto-matching.

notes

string

Optional free-text notes about the submitted documents (for example, what they contain or which site they belong to). Shared with document processing as background context.

Response

Status of a document upload job, including created documents and files that were duplicates, non-utility, password-protected, or failed processing.

string

required

The ID of the job.

Maximum string length: 255

status

enum<string>

required

The current status of the job, one of: PENDING, COMPLETED, FAILED. COMPLETED includes jobs that produced no new documents (duplicates, non-utility files, password-protected files, or processing errors). If the job status is FAILED, please contact our support team.

PENDING - Pending
COMPLETED - Completed
FAILED - Failed

Available options:

PENDING,

COMPLETED,

FAILED

parsedDocumentIds

string[]

List of document IDs that were processed successfully by the job. This is only populated if the job is completed. Empty when the job finished without creating new documents.

duplicates

integer

Number of duplicate files detected by the job. This is only populated if the job is completed.

duplicateDocumentIds

string[]

List of document IDs that were identified as duplicates by the job. This is only populated if the job is completed.

nonUtilityDocumentIds

string[]

List of document IDs that were identified as non-utility documents by the job. This is only populated if the job is completed.

passwordProtectedDocumentIds

string[]

List of document IDs that were identified as password-protected by the job. This is only populated if the job is completed.

errorDocumentIds

string[]

List of document IDs that failed processing. This is only populated if the job is completed.

terminationReason

string | null

The reason the job failed. This is only populated if the job status is FAILED.

Accounts

Companies

Webhook Portal

Connections

Documents

Intervals

Invitations

Jobs

Meters

Ping

Sites

Team

Usage Data

Webhook Payloads

Submit Job via Bulk Document Upload

Authorizations

Path Parameters

Body

Response