PetroMon Integration
OMC · BDC · Depot · Marker · Regulator

PetroMon, as an API

Submit orders, drive stage transitions, and receive signed lifecycle events — without the PetroMon web UI. Scope, validation and compliance stay exactly where they already are.

Get started API reference
No new source of truthCodes, never internal idsRetries are safe
terminal
$ curl \
  ".../api/v1/orders/PCLG40220002" \
  -H "X-Api-Key: ptm_live_..."

{
  "orderNumber": "PCLG40220002",
  "status": "good_standing",  // a name, never a number
  "depotCode": "BOSD0000040"
}
OMCBDCDEPOT
8
Lifecycle stages, one API
5
Partner types, scoped automatically
HMAC
Signed webhooks with replay

The lifecycle

One order, eight stages

Every partner drives the stages it owns and observes the rest. Pipeline orders skip the BRV check; non-markable products skip marking — and you're told when they do.

  1. 01
    Ordered
    OMC
  2. 02
    BDC approved
    BDC
  3. 03
    Good standing
    automatic
  4. 04
    Depot approved
    Depot
  5. 05
    BRV checked
    Depot
  6. 06
    Loaded
    Depot
  7. 07
    Marked
    Marker
  8. 08
    Released
    GRA

Statuses are names — loaded, released — never the underlying integers, which are not ordered by progress.

How it fits

A front door, not a second system

Your systems talk to the gateway. The gateway talks to PetroMon, which keeps doing everything it already does — including the external filings.

Your systems

ERP, TMS, depot software

REST + API key

Integration Gateway

Auth · scope · validation · idempotency · audit

Signed webhooks back to you

PetroMon core

The order lifecycle and its rules

ICUMS · UniPass · Ascent · Authentix

The gateway holds no order state of its own. Nothing it returns is a cached opinion — it is read from PetroMon at the moment you ask.

Who it's for

Built for every party on an order

Your company's PetroMon registration decides what you can drive and what you can see. Nothing is asserted in a request.

OMC

Drives
Raise and cancel orders
Sees
Every stage on its own orders

BDC

Drives
Approve, decline or cancel
Sees
Orders where it is the named BDC

Depot

Drives
Depot approval, BRV check, loading, cancellation, custody
Sees
Orders at its depot

Marking company

Drives
Marking, tagging, certificates
Sees
Orders it marks

Regulator

Drives
Release
Sees
Read-only across scope

What you get

Built for systems, not screens

The things that matter when an integration runs unattended against a regulatory system.

Events, not polling

Signed webhooks for every transition, with retries, dead-lettering, secret rotation and manual replay.

Automatic steps included

PetroMon skips the BRV check for pipeline orders and marking for non-markable products. Those reach you too, flagged as automatic.

Scope you can't get wrong

What you see comes from your company's PetroMon registration, never from the request. A BDC sees the orders it is named on.

Credentials with limits

One key per account, carrying your PetroMon licences. Set an expiry and an IP allowlist, and revoke it without touching the others.

Answerable support

Every call is recorded with its payload, response and requestId — so a rejection is explainable, not guesswork.

Built on PetroMon itself

The same stock lockdowns, product restrictions, BRV capacity and ICUMS checks. One source of truth, not a copy.

Getting started

Three steps to your first call

You are calling the same PetroMon your web users already work in — so a key is live from the moment it is issued, and scoped to your own companies alone.

  1. 1RegisterWith your PetroMon account reference. Every company under it comes across at once.
  2. 2Confirm the contact addressWe show it masked; you type it back, and the link goes there.
  3. 3Create a keyIt covers every company you operate. Then call the API.
Register API reference
terminal
$ curl \
  "/api/v1/orders" \
  -H "X-Api-Key: ptm_live_…"

{
  "items": [
    { "orderNumber": "PCLG40220002",
      "status": "good_standing",
      "parties": { "bdcCode": "BDC001" } }
  ],
  "totalCount": 101
}

Before you ask

The questions that come up first

Is this a copy of PetroMon's data?

No. The gateway holds no order state of its own. It authenticates, authorises, validates shape and delegates — every order you read is read from PetroMon at that moment.

What happens if my endpoint is down?

Delivery retries with backoff for up to 24 hours, then dead-letters. Nothing is lost: every event keeps its exact signed payload and can be replayed from the portal once you are back.

Can I accidentally see another company's orders?

No. Scope comes from your company's PetroMon registration, not from anything you send. An order outside it returns 404 rather than 403, so the response cannot even confirm it exists.

Do I need to handle PetroMon's status numbers?

Never. You send names and read names — approve with "bdc_approved", decline with "bdc_declined", and every response says loaded, released, cancelled. The gateway turns names into PetroMon's numbers, which are not ordered by progress and should never be compared.

Is a retry safe?

Yes. Send an Idempotency-Key and a repeated request replays the original response instead of acting twice. Order numbers are unique per company as a second guard.

Something else?

The reference covers every endpoint, object and error code.

Read the API reference

Ready to connect your systems?

Register with your PetroMon code, issue a key, and point your ERP at the same order lifecycle your operations team already works in.

Register Read the quickstart