# Energy Connect — Public API, full endpoint inventory

> Every operation in the Energy Connect public REST API: 135 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 a logistics platform that specializes today in 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 see buy, sell, and rack prices on every deal, carriers
and distributors haul them, and
customers order and receive. The data model follows how bulk liquid moves: 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 (4)

GET /me — The company the calling key acts for, its scopes, and whether it is a sandbox key (platform:usageread — auto-granted on every key).
GET /usage/me — Own quota + burst state for the calling key (platform:usageread — auto-granted on every key).
POST /api-keys/me/revoke — Revoke the calling key immediately (platformapikeys:manage) — cannot be undone.
POST /api-keys/me/rotate — Rotate the calling key (platformapikeys:manage) — returns the successor raw key ONCE; the calling key stays valid for 24h, and cannot be rotated again.

## 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 (7)

GET /locations — List locations.
GET /locations/{id} — Get location detail.
GET /locations/{id}/assets/{assetId}/history — A tank's level over time with the burn rate behind it. Readings come from the tank monitor (TankReading, EC-908) with outliers flagged by a rolling median + MAD, never deleted; fills come from delivered orders into the location for this tank's product. The baseline is a median (Theil–Sen over readings, or the median per-interval delivery rate) so a game-night spike never moves it. Which source wins follows the company's OrderSettings.tankLevelSource. Returns the reorder point and low limit as percentages, and days until each at the baseline rate. Public API (EC-4806): locations:read; the location must belong to your company or a subsidiary, otherwise 404.
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 (47)

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}/driver-position — The driver's most recent position on a load in transit, rounded to roughly a kilometre and carrying NO identity. Over the public API (EC-4781) only the poster's own key is served: the carrier's key and any other company's key get 404. In the portal the poster, the hauling carrier and the broker in between can see it, and a caller with no claim gets { position: null }. Otherwise position is null when there is no fix, when the newest fix is stale, or when the load is not moving.
GET /orders/{id}/my-bid — GET /orders/{id}/my-bid.
GET /orders/{id}/notes — List an order's notes (chronological).
GET /orders/{id}/timeline — Order status history, oldest first. Owner, carrier or assigned broker; the poster and broker also see forwarded children's rows, and the downstream carrier is never named to the poster.
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. Accepts isExtraction (EC-3717) to mark — or, sent as false, to un-mark — the order as a pump-out; this is the only surface that can clear the flag, since order edits close at INTRANSIT. Rejected on a split load.
PATCH /orders/{id}/po — Set or change an order's PO number (own orders only), in any status except CANCELLED, including after delivery and invoicing (EC-1354). Linked invoices that are not void take the new PO. Null clears it.
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}/broker-accept — Broker accepts a load posted to it — ASSIGNED becomes CONFIRMED.
POST /orders/{id}/broker-decline — Broker declines a load posted to it — the order goes back to the poster as a DRAFT.
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. On /v1/public/ it auto-advances the order to INTRANSIT; the portal route stops at CONFIRMED (Load complete) and start-transit is a separate step. 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. PUMP-OUT (EC-3717): send isExtraction: true when the job turned out to pull product OUT of the tank — gallons stay positive magnitudes and the order-level isExtraction flag carries the direction. Rejected on a split load, which records a pump-out as a negative stop allocation instead.
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}/forward — Broker duplicates an accepted (CONFIRMED) parent order into a child direct order assigned to a connected carrier — parent stays CONFIRMED (hop depth 1; a child cannot itself be forwarded).
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. Required after a portal confirm-pickup, which stops at CONFIRMED (Load complete). Optional on /v1/public/ — confirm-pickup auto-advances there, and an order already in transit returns success.
POST /orders/{id}/tracking-link — Mint a customer tracking link for a load you posted. The URL opens an auth-less page showing what is coming, the delivery window, the live ETA, a rough anonymous driver position while in transit, and proof-of-delivery files once delivered — never the carrier, driver, prices or document numbers. Minting again revokes every earlier link for the load, so a link already sent stops working. Not available for split loads. Over the public API (EC-4781) only the poster's own key can mint: the carrier's key and any other company's key get 404.
POST /orders/{id}/verify — Verify (approve) or reject a submitted delivery (own orders only). Approve moves the order to INVOICED; reject sends it back to the carrier to correct and requires notes as the reason.
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.
PUT /orders/{id}/ship-to-erp-id — Set or replace your ERP code (station id) for an accepted haul's delivery site.

## 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 upsert rack prices — each line updates the latest posting for its terminal × product × brand or adds a new posting (later different price, or a future effectiveAt), the same rule as PUT /pricing/master. One transaction per batch; MANAGER+.
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).