Submit Job via Single Document Upload

curl --request POST \
  --url https://external.nectarclimate.com/v2.1/job/company/{company_id} \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-KEY: <api-key>' \
  --form document='@example-file' \
  --form siteId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form accountId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form 'notes=<string>'

import requests

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

files = { "document": ("example-file", open("example-file", "rb")) }
payload = {
    "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "notes": "<string>"
}
headers = {"X-API-KEY": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('document', '<string>');
form.append('siteId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('accountId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('notes', '<string>');

const options = {method: 'POST', headers: {'X-API-KEY': '<api-key>'}};

options.body = form;

fetch('https://external.nectarclimate.com/v2.1/job/company/{company_id}', 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.1/job/company/{company_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "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.1/job/company/{company_id}"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("X-API-KEY", "<api-key>")

	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.1/job/company/{company_id}")
  .header("X-API-KEY", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

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

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

Jobs

Submit Job via Single Document Upload

Submits a document to Nectar for processing and creates a job to track its progress. The company must be active to submit a job. Each document submission is tracked as a job with an id that can be used to check processing status. This endpoint returns the jobId immediately while processing continues asynchronously. Note that since this endpoint requires a file upload, the request body must be form-data. The size limit for the utility bill is 25MB, and the page limit for a submitted PDF file is 800. You can also pin the document to a specific site or utility account by passing the corresponding siteId and/or accountId. When provided, the parsed bill 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}

Submit Job via Single Document Upload

curl --request POST \
  --url https://external.nectarclimate.com/v2.1/job/company/{company_id} \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-KEY: <api-key>' \
  --form document='@example-file' \
  --form siteId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form accountId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form 'notes=<string>'

import requests

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

files = { "document": ("example-file", open("example-file", "rb")) }
payload = {
    "siteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "notes": "<string>"
}
headers = {"X-API-KEY": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('document', '<string>');
form.append('siteId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('accountId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('notes', '<string>');

const options = {method: 'POST', headers: {'X-API-KEY': '<api-key>'}};

options.body = form;

fetch('https://external.nectarclimate.com/v2.1/job/company/{company_id}', 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.1/job/company/{company_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "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.1/job/company/{company_id}"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("X-API-KEY", "<api-key>")

	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.1/job/company/{company_id}")
  .header("X-API-KEY", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"document\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"siteId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"accountId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"notes\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "id": "<string>",
  "parsedDocumentIds": [
    "<string>"
  ],
  "duplicates": 123,
  "duplicateDocumentIds": [
    "<string>"
  ],
  "nonUtilityDocumentIds": [
    "<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 the job.

Body

multipart/form-data

Serializer for form fields during job submission.

document

file

required

File object representing the document to be processed by the job.

siteId

string<uuid> | null

UUID of the site to pin the document to. When provided, the parsed bill is allocated to this site instead of relying on best-effort auto-matching.

accountId

string<uuid> | null

UUID of the utility account to pin the document to. When provided, the parsed bill 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 document (for example, what it contains or which site it belongs to). Shared with document processing as background context.

Response

Serializer for the response of job status endpoint.

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, TERMINATED, FAILED.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.

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.

terminationReason

string

The reason the job was terminated. This is only populated if the job is terminated.

Get Job Status Details Submit Job via Bulk Document Upload

⌘I