Does Oracron provide a freight invoice audit API?

Yes. Oracron Sentra exposes a REST API for programmatic freight invoice audit: upload a PDF invoice, retrieve shipment-level audit results once the pipeline completes, submit a human review decision per shipment, and subscribe to webhook events for status changes. The API is in developer preview — keys are issued on request to design partners.

How does authentication work on the Oracron API?

Every request carries a Bearer token in the Authorization header. Keys are scoped to one organisation and are not self-serve during the preview; contact us to receive one. All requests must be HTTPS.

Which freight invoice file formats does the Oracron API accept?

PDF invoices (AI-extracted via Claude), CSV carrier exports for the formats currently mapped (DHL Freight, Kühne+Nagel, DSV, and similar), and forwarder-aggregator CSVs. The pipeline detects the input type and routes it to the correct extractor; multi-invoice PDFs (Sammelrechnung) are auto-detected.

What webhook events does Oracron emit for an audited invoice?

Webhooks fire when an invoice completes ingestion, when each shipment finishes rate validation, when a dispute letter is generated, when a carrier replies via the dispute portal, and when Resend confirms email delivery / open / bounce. Each event carries the invoice and shipment IDs so the consumer can correlate with prior state.

Where is the Oracron API hosted and is it GDPR-compliant?

EU customers' API requests hit endpoints inside AWS eu-central-1 (Frankfurt) and the underlying Postgres + storage stays in-region. Tenant separation is enforced by Postgres row-level security. A Data Processing Agreement is available on request. See /eu-gdpr-freight-audit for the full compliance stack.

Is the Oracron API generally available?

Not yet. The API is in developer preview — endpoints and field names described in the reference may change. Production-grade availability and self-serve key issuance ship together; design partners get access today on request.

Developer Preview · API access by request

REST API Reference

Automate invoice ingestion, retrieve shipment-level audit results, submit review decisions, and receive real-time webhook events. The Oracron API is designed for freight finance teams that want to connect Sentra to their ERP, TMS, or custom tooling. It is in active development — the reference below describes the planned surface and is offered to early design partners on request.

Base URL https://oracron.app/api/v1

Auth Bearer API key

Format application/json

Authentication

All API requests must include a valid API key as a Bearer token in the Authorization header. API keys are generated per workspace in Settings → API access.

Request header

Authorization: Bearer or_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Developer preview note

The API is in active development and not yet generally available — endpoints and fields described here may change. Keys are not self-serve; during the preview period they are issued on request to design partners. Contact us to receive a sandbox key.

Errors & status codes

The API uses standard HTTP status codes. Error responses include a machine-readable error code and a human-readable message.

Error response body

{
  "error": "invoice_not_found",
  "message": "No invoice with id inv_9xk2 exists in this workspace.",
  "status": 404
}

Status	Meaning
200	Success
201	Resource created
400	Bad request — missing or invalid parameters
401	Unauthorised — missing or invalid API key
403	Forbidden — key lacks permission for this resource
404	Not found
422	Unprocessable — file could not be parsed
429	Rate limit exceeded

Rate limits

Limits apply per API key. Current limits during developer preview:

Endpoint group	Limit
Invoice ingest (upload)	60 / hour
Read endpoints (GET)	1000 / hour
Review submission	200 / hour

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Invoices

GET /invoices List all invoices

Returns a paginated list of invoices in your workspace, ordered by upload date descending.

Query parameters

status	optional	Filter by status: `pending` · `mapped` · `review` · `audited` · `dispute`
carrier_id	optional	Filter by carrier entity ID
limit	optional	Max results per page (default 50, max 200)
cursor	optional	Pagination cursor from previous response

Response 200

{
  "data": [
    {
      "id":           "inv_9xk2mR4nQp",
      "carrier_name": "DB Schenker GmbH",
      "invoice_date": "2024-03-01",
      "total_amount": 14220.40,
      "currency":     "EUR",
      "line_count":   24,
      "status":       "audited",
      "uploaded_at":  "2024-03-02T09:14:22Z"
    }
  ],
  "meta": {
    "total":        847,
    "next_cursor":  "eyJpZCI6ImludiJ9"
  }
}

GET /invoices/{id} Get a single invoice

Returns full detail for a single invoice including extracted line summary, audit flags, and processing metadata.

Response 200

{
  "id":              "inv_9xk2mR4nQp",
  "carrier_name":    "DB Schenker GmbH",
  "carrier_id":      "car_schenker_de",
  "invoice_number":  "SCH-2024-031-08841",
  "invoice_date":    "2024-03-01",
  "total_amount":    14220.40,
  "currency":        "EUR",
  "line_count":      24,
  "flagged_count":   2,
  "disputed_amount": 312.80,
  "status":          "audited",
  "file_format":     "pdf",
  "sub_invoices":    1,
  "uploaded_at":     "2024-03-02T09:14:22Z",
  "audited_at":      "2024-03-02T09:14:55Z"
}

POST /invoices/ingest Upload & extract invoice

Upload an invoice file and trigger the full pipeline: AI extraction → fee-code mapping → shipment enrichment → carrier matching → rate validation. One invoice may resolve to several shipments — the audit unit — each validated against your contracted rates. For PDF files, multi-invoice (Sammelrechnung) detection is automatic. Accepts multipart/form-data.

Body (multipart/form-data)

file	required	Invoice file. Accepted: `.pdf`, `.csv`, `.edi` (Professional+ only)
carrier_hint	optional	Carrier name or ID to pre-seed detection (improves accuracy for edge cases)
metadata	optional	JSON object — arbitrary key/value pairs stored against the invoice (e.g. your internal reference)

Example request (curl)

curl -X POST https://oracron.app/api/v1/invoices/ingest \
  -H "Authorization: Bearer or_live_xxxx" \
  -F "file=@schenker-march-2024.pdf" \
  -F "carrier_hint=DB Schenker" \
  -F 'metadata={"your_ref":"PO-2024-0312"}'

Response 201

{
  "id":          "inv_9xk2mR4nQp",
  "status":      "pending",
  "message":     "Invoice accepted. Extraction pipeline started.",
  "webhook_event": "invoice.audited" // fired when pipeline completes
}

Processing is asynchronous. Poll GET /invoices/{id} or listen for the invoice.audited webhook event to know when results are ready.

GET /invoices/{id}/lines Get extracted lines

Returns all extracted charge lines for an invoice, including the mapped fee code, confidence score, and any rate validation flags.

Response 200 — line object

{
  "id":                "line_7wQm3p",
  "invoice_id":        "inv_9xk2mR4nQp",
  "description":       "Kraftstoffzuschlag",
  "fee_code":          "FUEL_SURCHARGE",
  "fee_code_label":    "Fuel surcharge",
  "amount":            184.60,
  "currency":          "EUR",
  "contracted_amount": 160.00,
  "delta":             24.60,
  "confidence":        0.97,
  "status":            "flagged",
  "flag_reason":       "exceeds_contracted_rate",
  "shipment_ref":      "SHP-20240301-0041"
}

Review Queue

GET /review-queue List pending review items

Returns all invoice lines currently in the review queue — lines where mapping confidence fell below the auto-approve threshold, or where no rate was found on file.

Response 200 — item object

{
  "id":                 "rev_4pLn8w",
  "line_id":            "line_7wQm3p",
  "invoice_id":         "inv_9xk2mR4nQp",
  "carrier_name":       "DB Schenker GmbH",
  "original_description": "Sicherheitszuschlag AWB",
  "ai_suggested_code":  "SECURITY_SURCHARGE",
  "confidence":         0.61,
  "amount":             42.00,
  "queued_at":          "2024-03-02T09:15:01Z"
}

POST /review-queue/{id}/decision Submit review decision

Submit an approve, override, or dispute decision for a queued line. Override decisions automatically create an alias to improve future auto-mapping.

Body (JSON)

action	required	`approve` · `override` · `dispute`
fee_code	optional	Required when action is `override`. The correct fee code to assign.
note	optional	Free-text note stored against the decision for audit trail.

Example — override decision

{
  "action":   "override",
  "fee_code": "SECURITY_SURCHARGE",
  "note":     "Confirmed via carrier rate sheet March 2024"
}

Response 200

{
  "id":        "rev_4pLn8w",
  "status":    "resolved",
  "action":    "override",
  "alias_created": true,
  "resolved_at": "2024-03-02T11:30:00Z"
}

Fee Codes

GET /fee-codes List your fee code library

Returns all fee codes in your workspace, including your custom aliases. Useful for building integrations that map Oracron codes to your internal cost centre taxonomy.

Response 200 — fee code object

{
  "code":          "FUEL_SURCHARGE",
  "label":         "Fuel surcharge",
  "service_family": "SURCHARGE",
  "transport_mode": "ROAD",
  "aliases": [
    "Kraftstoffzuschlag",
    "KSZ",
    "Fuel adj."
  ],
  "is_custom": false
}

Webhooks

Oracron can push events to your endpoint as invoices move through the pipeline — no polling required. Register a webhook URL in Settings → Webhooks.

Webhook payload structure

{
  "event":      "invoice.audited",
  "created_at": "2024-03-02T09:14:55Z",
  "data": {
    // full invoice object
  },
  "signature":  "sha256=abcdef..." // HMAC-SHA256, verify before processing
}

Signature verification

Always verify the X-Oracron-Signature header before acting on a webhook. Compute HMAC-SHA256 of the raw request body using your webhook secret (from Settings). Reject requests where signatures don't match.

Event types

Event	Fired when
invoice.ingested	Invoice file uploaded and accepted
invoice.audited	Full pipeline complete — results ready
invoice.review_required	One or more lines entered the review queue
review.item_resolved	A review queue item was approved, overridden, or disputed
review.queue_cleared	All queue items for an invoice resolved
invoice.ingest_failed	Pipeline failed — file could not be processed

Developer Preview

Ready to connect?

API access is available on Professional and Enterprise plans. Contact us to receive a sandbox key and test the full pipeline against your own invoices.

Request API access View pricing

REST API Reference

Authentication

Errors & status codes

Rate limits

Invoices

Review Queue

Fee Codes

Webhooks

Webhooks

Ready to connect?

Sign in

Reset password