Intangible Asset Valuation API: The Opagio Developer Guide

Most finance teams meet their valuation data through a screen. That works until the data needs to live somewhere else — a board pack assembled every quarter, an internal data warehouse, a lender reporting template, or an investor update that has to reconcile against the management accounts.

Opagio Public API v1 exists for that second case. It is a small, deliberately read-oriented REST surface that lets your systems pull the intangible asset valuations and company records already held in your Opagio organisation, without a person exporting anything by hand.

This guide documents what the API does today, verified against the shipped code rather than a roadmap. Where a capability does not exist, this guide says so.

What Public API v1 covers

Two properties shape everything else. First, the API is org-scoped: every request is bound to exactly one organisation — the one that owns the key — and cross-tenant reads are not possible. Second, it is API-key authenticated, not session-cookie authenticated, so it is a separate path from the browser application and is not affected by anyone's login state.

Step 1 — Issue an API key

Keys are not created through the API. They are issued inside the platform, under Settings → API keys, by a user holding the API_MANAGE_KEYS permission in an organisation that has the api-access feature flag enabled. If the flag is off for your organisation, the key-issuance page will not mint a key — speak to your account contact before you plan an integration around it.

A newly created key is granted four scopes by default: read:valuations, read:portfolio, read:webhooks and write:webhooks.

The same page lists your existing keys by prefix and revokes them. A revoked key, or one past its expiry date, is rejected immediately on the next call.

Step 2 — Authenticate a request

Every call carries the key as a bearer token:

Authorization: Bearer opagio_pk_<64 hex characters>

The prefix and the total length are validated before any database lookup. A key is opagio_pk_ followed by 64 hexadecimal characters — 74 characters in total. Anything else is rejected on format alone, which means a truncated or padded key fails fast rather than being treated as an unknown credential.

Authentication failures and what they mean

These are deliberately distinguishable. A client that retries on Invalid API key format. has a bug in its configuration handling; a client that sees API key has been revoked. should stop and alert a human rather than retry.

Step 3 — Understand the four scopes

Each key carries a permissions array. Every endpoint checks the one scope it needs and returns 403 with Insufficient permissions. if it is absent.

Scope-to-endpoint mapping

The GET /widget/:orgId endpoint is the exception: it checks no named scope, and instead requires the key's organisation to equal the :orgId in the path. A mismatch returns 403.

Step 4 — Budget for two rate-limit ceilings

This is the detail most integrations get wrong, because there are two independent limits and a call must satisfy both.

The per-IP ceiling is applied before authentication, as a coarse anti-abuse guard. The per-key ceiling is applied after authentication, keyed on the authenticated key, and its budget is selected from the key's rate-limit tier. The standard tier is 300 requests per 15-minute window, and an unrecognised or absent tier falls back to the same default.

The two are additive constraints, not alternatives. Spreading one key's traffic across many source addresses does not buy extra throughput, because the per-key ceiling still applies. Equally, several keys behind one office IP share the per-IP budget between them.

The two limits return different messages, which is how you tell them apart in logs:

Step 5 — Read valuations and company records

Valuation reports are listed newest-first and scoped to your organisation. The internal userId field is stripped from every record before it leaves the API.

curl -s https://opag.io/api/v1/valuations \
  -H "Authorization: Bearer $KEY"

GET /valuations/:id returns a single report in the same shape. A report belonging to a different organisation returns 404, not 403 — the API reports another tenant's resource as absent rather than as forbidden, so existence itself is never leaked.

The read endpoints at a glance

The health classification on company records is derived from intangibles intensity rather than stored. For company-type organisations the records also carry a resolved sector, industryCategory and sicCode.

GET /widget/:orgId returns companyCount, totalEV, weightedAvgTFP and totalIntangibles. Where the organisation has no companies, it returns companyCount and totalEV as zero. The totalEV figure is enterprise value and weightedAvgTFP is weighted average total factor productivity.

Step 6 — Handle pagination and the response envelope

List endpoints accept page and per_page. Both are clamped server-side, so an out-of-range value is corrected rather than rejected.

List responses echo the values actually applied — { "data": [ … ], "page": 1, "per_page": 25 } — so a client should read the echoed values rather than assume its request was honoured verbatim. Pagination is offset-based.

Three response envelopes cover the whole surface. Reads and creates return { "data": … }. Updates and deletes return { "success": true }. Failures return { "error": "<message>" }.

Status codes you should handle

Every v1 response carries an X-API-Version header of the form 1.0.<build marker>. It is set before authentication runs, so even a 401 carries it — useful when you are debugging whether a request reached the API at all.

Step 7 — Subscribe to events (briefly)

The API also manages outbound webhook subscriptions: POST /webhooks registers an HTTPS URL against a list of event names, and returns a signing secret once, in the creation response. Deliveries arrive as a POST carrying X-Opagio-Event and an X-Opagio-Signature header containing a hex HMAC-SHA256 of the raw body, keyed with that secret. Verify it against the exact raw bytes.

One caveat worth stating now: registering an event name does not guarantee traffic. A number of names in the catalogue are declared for future use and have no emitter wired behind them yet. A subscription to one of those is accepted and will simply never fire.

What the API does not do

Being precise about absence is more useful than an aspirational feature list.

• It does not accept financial data for valuation. There is no endpoint that takes inputs and returns a computed valuation. Valuations are produced in the platform; the API reads the results.
• It does not write portfolio data. There are no create, update or delete endpoints for companies or valuations. The only writes on the surface are webhook subscriptions.
• It does not expose benchmarking or questionnaire endpoints.
• There is no published OpenAPI or Swagger schema, and no client SDKs. Any HTTP client will do; there is nothing to install.

A sensible first integration

A first integration that works well in practice is a scheduled pull rather than an event-driven one. Run a job on your reporting cadence, page through GET /portfolio/companies, store the response against your own record of the period, and keep the raw JSON alongside the parsed figures so that you retain an audit trail of exactly what the API returned on the day you pulled it.

That last point matters more than it sounds. Valuation figures move as underlying data is refreshed. A stored response with a timestamp is the difference between a board pack you can defend and one you can only re-run.

Once that job is stable, add a webhook subscription so the pull can be triggered by an event instead of a clock. Doing it in that order means you always have a working fallback if a delivery is missed.

Related reading

• Connect Xero to Opagio: the integration setup guide — the OAuth flow and what data syncs
• Import a CSV to Opagio — the manual path into the same data the API reads
• FAQ: Can I export my Opagio valuation for use in external documents?
• FAQ: Is Opagio data secure and encrypted?
• Glossary: API economy