# Energy Connect — Public API, full endpoint inventory

> Every operation in the Energy Connect public REST API: 122 endpoints
> across 17 resource groups. Generated from the OpenAPI 3 contract,
> not hand-maintained.

This is the machine-readable companion to https://energyconnecter.ai/api-docs,
whose endpoint browser is rendered client-side and is therefore invisible to
crawlers that do not execute JavaScript.

## What this API belongs to

Energy Connect is vertical software for the bulk liquid supply chain — moving
petroleum, propane, lubricants and chemicals from a terminal rack to an end
user's tank. Suppliers publish live rack pricing, brokers post loads and track
margins, carriers and distributors haul them, and customers order and receive.
It is not a general freight platform with a fuel setting: bills of lading are
modelled per pickup stop, volumes carry both gross and temperature-corrected
net quantities, allocations are per terminal, product and period, and one
pickup can serve several drops.

This API is the same surface the product runs on. It exists so a fuel
distributor, jobber, brokerage or carrier can connect ordering, dispatch,
bill-of-lading capture, delivery tickets and invoicing to the systems they
already run, rather than replacing them.

Base URL: https://api.energyconnecter.ai/v1/public
OpenAPI contract: https://api.energyconnecter.ai/openapi.json
Human documentation: https://energyconnecter.ai/api-docs
Integration guide: https://energyconnecter.ai/api-getting-started

Authentication: an `X-API-Key` header or an `Authorization: Bearer` token.
Keys are prefixed `ec_live_` (production) or `ec_test_` (sandbox).
Every write requires an `Idempotency-Key` header.

## Allocations (3)

GET /allocations — List allocations by terminal.
POST /allocations — Upsert allocation state by natural key (terminal + product + period).
PUT /allocations/{id} — Update an allocation by id (capacity/allocated/status only — natural key is immutable).

## API Keys (1)

GET /usage/me — Own quota + burst state for the calling key (platform:usageread — auto-granted on every key).

## Companies (9)

DELETE /companies/products/{id} — Remove product.
GET /companies/products — List company product catalog (branch keys with no rows inherit the HQ catalog read-only — EC-2013).
GET /companies/services — List your services catalog.
GET /companies/{id}/profile — Get a company public profile (own company via tenant scope).
POST /companies/products — Add product to catalog.
PUT /companies/products — Reconcile the FULL active product set (EC-1256: absent rows deactivate; empty array deactivates all — the nightly back-office sync shape).
PUT /companies/products/{id} — Update product.
PUT /companies/services — Reconcile the FULL active service set (absent rows deactivate; empty array deactivates all).
PUT /companies/{id}/profile — Update your company profile (strict allowlist mirroring the read shape; unknown fields 400).

## Connections (12)

DELETE /freight-rates/{id} — Delete a freight rate.
GET /connections — List connections.
GET /connections/{id} — Get connection by id.
GET /connections/{id}/freight-rates — List freight rates for a connection.
GET /connections/{id}/loading-numbers — Loading-number catalog for a connection — both directions, supplierId-attributed.
POST /connections/requests — Send a connection request to another company.
POST /connections/{id}/accept — Accept an incoming pending connection request.
POST /connections/{id}/decline — Decline an incoming connection request (receiver only).
POST /connections/{id}/disconnect — Sever an ACCEPTED connection (either party; data preserved).
POST /connections/{id}/freight-rates — Create freight rate on a connection.
PUT /connections/{id}/loading-numbers — Full-replace your OWN direction of the loading-number roster (rows the counterparty issued you).
PUT /freight-rates/{id} — Update a freight rate.

## Customers (1)

POST /customers — Create a customer in the caller's network.

## Invoices (12)

DELETE /invoices/{id}/documents/{fileId} — Remove a supporting document (issuer only; never the primary external upload; blocked while DISPUTED).
GET /invoice-amendments — List invoice amendments across your invoices (issuer or payer side).
GET /invoice-amendments/{id} — Get an invoice amendment (issuer or payer).
GET /invoices — List invoices (filterable by status).
GET /invoices/{id} — Get invoice by id.
GET /invoices/{id}/pdf — Download invoice PDF.
POST /invoice-amendments — Propose an amendment to an issued invoice (issuer only; one PENDING per invoice).
POST /invoice-amendments/{id}/approve — Approve a pending amendment (payer only) — applies the changes atomically.
POST /invoices — Create invoice.
POST /invoices/{id}/documents — Attach supporting documents to an invoice (issuer only; upload with context invoicedoc first).
POST /invoices/{id}/issue — Issue a DRAFT invoice (DRAFT → OUTSTANDING; notifies the payer).
PUT /invoices/{id}/mark-paid — Mark invoice as paid.

## Load Board (3)

GET /orders/load-board — The carrier load board — open loads, disintermediation-masked (no end-customer identity; hasBids boolean, never a count).
POST /orders/{id}/bids — Submit bid on an order.
PUT /orders/{id}/bids/{bidId}/decline — Decline a bid (with optional reason + carrier notification).

## Locations (6)

GET /locations — List locations.
GET /locations/{id} — Get location detail.
POST /locations — Create a delivery site (with optional contacts, schedules, assets).
POST /locations/{id}/assets — Add an asset (tank) to an existing location.
PUT /locations/{id} — Update a delivery site (partial; isActive toggles archiving from listings).
PUT /locations/{id}/assets/{assetId} — Update an asset (tank).

## Orders (38)

DELETE /orders/{id}/documents/{docId} — Delete a document (soft; owner or assigned carrier, within 36h of completion).
GET /delivery-tickets — List delivery tickets.
GET /delivery-tickets/{id} — Get delivery ticket.
GET /delivery-tickets/{id}/pdf — Download delivery ticket PDF.
GET /orders — List orders (paginated, filterable).
GET /orders/my-bids — GET /orders/my-bids.
GET /orders/{id} — Get order details.
GET /orders/{id}/bids — GET /orders/{id}/bids.
GET /orders/{id}/documents — List an order's documents (BOL, POD, tickets).
GET /orders/{id}/documents/{docId}/content — Stable document download link (302 to a freshly signed URL).
GET /orders/{id}/my-bid — GET /orders/{id}/my-bid.
GET /orders/{id}/notes — List an order's notes (chronological).
PATCH /orders/loads/{id}/sourcing — Fill blank pickup terminal/supplier per line (assigned carrier).
PATCH /orders/{id}/delivery — Edit a submitted delivery within the 36h post-completion window.
POST /delivery-tickets — Create delivery ticket.
POST /delivery-tickets/{id}/sign — Sign delivery ticket (driver / receiver).
POST /orders — Create new order.
POST /orders/{id}/accept — Accept an offered order (assigned carrier) — order becomes CONFIRMED.
POST /orders/{id}/assignee-cancel — Assignee escape hatch — cancel a committed order pre-delivery.
POST /orders/{id}/cancel — Cancel an order (own orders only; not after delivery).
POST /orders/{id}/confirm-pickup — Confirm pickup — multi-BOL payload (bols[] + per-line actuals) or empty body to advance state; auto-advances the order to INTRANSIT. Per line, the loaded-from supplier is supplierId (directory UUID) OR supplierName (ad-hoc plain text for a supplier not on the platform) — never both. lines[] is matched by orderLineIndex, never by product name: one entry per ordered line — set loadedProduct to the product name actually loaded when it differs from (or is just your name for) the ordered one; it is stored as a substitution and shown on the order. addedLines is for product loaded BEYOND the order. If you cannot map the ordered lines at all, send lines: [] with the whole load in addedLines — every ordered line is recorded as not loaded and the added lines carry the actuals UNPRICED (the office prices them by hand).
POST /orders/{id}/decline — Decline an offered order — waterfall advances or the board reopens.
POST /orders/{id}/delivery — Submit delivery data (meter, stick, receiver); on a load-complete order this performs the transit hop itself. SPLIT LOAD (EC-2577): send deliveryStopId (plus allocations[] rows of {allocationId, deliveredQuantity, deliveredGrossQuantity?}, or skipped+skipReason) to resolve ONE stop — call once per stop, ids from the order detail read; the last stop completes the order. A whole-order body (no deliveryStopId) is rejected on a split load. A line added at the rack (lines[].addedAtDelivery: true) has NO allocation row and therefore no allocationId — report it in addedLines[] rows of {lineId, product, unitCode, deliveredQuantity, deliveredGrossQuantity?}, where lineId is that line's lines[].id. Omitting lineId CREATES a second added line instead of recording the delivery of the existing one. addedLines[] alone may resolve a stop.
POST /orders/{id}/dispatch — Dispatch a driver (SMS/email) or self-dispatch.
POST /orders/{id}/documents — Attach a document to an order (step 2 — register by fileUploadId).
POST /orders/{id}/eta — Set/update the carrier ETA on a confirmed order (non-blocking follow-up).
POST /orders/{id}/notes — Append a note to an order (any status).
POST /orders/{id}/notify-delivered — Report delivery to the originator (no status change; one notification per order).
POST /orders/{id}/publish — Publish order (DRAFT → POSTED) — sends a carrier-addressed order as an offer, otherwise posts to the load board.
POST /orders/{id}/reconfirm — Reconfirm a haul after the poster edited material terms (assigned carrier).
POST /orders/{id}/start-transit — Load complete → in transit (optional — confirm-pickup auto-advances; idempotent success when already in transit).
POST /uploads — Request a signed upload URL (step 1 of attaching a document).
PUT /delivery-tickets/{id} — Update delivery ticket.
PUT /orders/{id} — Update order.
PUT /orders/{id}/bids/{bidId}/accept — PUT /orders/{id}/bids/{bidId}/accept.
PUT /orders/{id}/bids/{bidId}/counter — PUT /orders/{id}/bids/{bidId}/counter.
PUT /orders/{id}/bids/{bidId}/re-counter — PUT /orders/{id}/bids/{bidId}/re-counter.
PUT /orders/{id}/bids/{bidId}/withdraw — PUT /orders/{id}/bids/{bidId}/withdraw.

## Payments (2)

GET /payments — List payments.
GET /payments/{id} — Get payment by id.

## Pricing (14)

GET /pricing/contract — Contract prices — role=supplier (own roster incl. scheduled) or role=customer (live rows issued to you).
GET /pricing/imports/product-aliases — List product aliases (raw sheet label → canonical product).
GET /pricing/imports/terminal-aliases — List terminal aliases (source feed code → your SupplierTerminal).
GET /pricing/imports/{id} — Import batch status + first-50 preview rows.
GET /pricing/rack — Get rack pricing.
GET /pricing/terminal/{id} — Rack prices for a specific terminal.
POST /pricing/bulk/rack — Bulk update rack prices.
POST /pricing/contract — Upsert contract prices for one connected customer (supplier side).
POST /pricing/freight-calculate — Calculate freight for an origin/destination/gallons combination.
POST /pricing/imports — Preview a price-sheet import from an uploaded file (context importcsv).
POST /pricing/imports/product-aliases — Create a product alias (used by the next commit).
POST /pricing/imports/terminal-aliases — Create a terminal alias (used by the next commit).
POST /pricing/imports/{id}/cancel — Cancel a PREVIEW batch (idempotent).
POST /pricing/imports/{id}/commit — Commit a PREVIEW batch into RackPrice rows (single-shot).

## Product Taxonomy (1)

GET /product-taxonomy/units — List the platform-global unit-of-measure catalog accepted by order-line unitCode.

## Reference Data (1)

GET /master-terminals — List IRS-seeded master terminals — the directory loading-number matching keys off.

## Supplier Terminals (5)

DELETE /supplier-terminals/{id} — Archive a supplier terminal (soft — stays GET-by-id resolvable with isActive: false).
GET /supplier-terminals — List supplier terminals.
GET /supplier-terminals/{id} — Get supplier terminal detail.
POST /supplier-terminals — Create a supplier terminal (EC-741).
PUT /supplier-terminals/{id} — Update a supplier terminal (EC-741).

## Suppliers (1)

POST /suppliers — Create a supplier in the caller's network.

## Tax Rates (5)

DELETE /tax-rates/{id} — Deactivate a tax rate (soft — history keeps referencing it).
GET /tax-rates — List your tax-rate schedule (filter: category, activeOnly, effectiveAt).
GET /tax-rates/{id} — Get a tax rate.
POST /tax-rates — Create a tax rate (PERUNIT or PERCENTAGE, optional product/customer rules).
PUT /tax-rates/{id} — Update a tax rate (rule arrays are full-replacement; omit to leave unchanged).

## Webhooks (8)

DELETE /webhooks/{id} — Delete a webhook subscription.
GET /webhooks — List webhook subscriptions.
GET /webhooks/{id} — Get a webhook subscription.
GET /webhooks/{id}/deliveries — Delivery history incl. dead-letters.
PATCH /webhooks/{id} — Update url/events/description/isActive.
POST /webhooks — Create a webhook subscription (response carries the signing secret ONCE).
POST /webhooks/{id}/replay — Re-enqueue events since a timestamp (catch-up; same stable event ids).
POST /webhooks/{id}/rotate-secret — Rotate the signing secret (response carries the new secret ONCE).