Documentation

Getting started

The API is served from https://api.duceusapi.com. Create an account, then generate a key on the API key page. Every account starts on the free plan, so you can make your first call right away:

curl "https://api.duceusapi.com/transactions?country=NL&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

List endpoints return a page envelope (items, total, limit, offset); see pagination. Which countries and data types are available is listed on the coverage page.

Authentication

Every endpoint except /health requires your API key as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You have one key per account; generating a new one revokes the previous one immediately. The key is shown once, at creation; store it in a secret manager, not in source control.

Rate limits

Requests are counted per key in fixed hourly windows that start on the hour (UTC). The limit depends on your plan. Every authenticated response carries the current state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1758294000

X-RateLimit-Reset is a Unix timestamp of the next window. Once the limit is exhausted, further requests return 429 with a Retry-After header (seconds). Rejected requests still count against the window, so back off rather than retrying in a tight loop.

Plan limits

Your plan sets how many requests you may make, and for each dataset which countries you may query and how far back the data goes.

How limits apply

• Asking for a country outside your plan returns 403, so you learn why rather than getting an empty list.
• Omitting the country filter returns rows from all countries your plan covers.
• Rows dated before your plan's history start for that dataset are not returned.
• /feed and /issuers span both datasets: each row follows its own dataset's limits.

Upgrade on the plan page; the new limits apply on the next request.

Pagination

List endpoints return at most 500 rows per request and wrap them in an envelope:

{
  "items": [ ... ],
  "total": 1284,
  "limit": 50,
  "offset": 0
}

Parameters

Every list endpoint accepts the same paging parameters alongside its own filters:

Walking the archive

Increase offset by limit until offset + items.length reaches total:

GET /transactions?country=NL&limit=500&offset=0
GET /transactions?country=NL&limit=500&offset=500
GET /transactions?country=NL&limit=500&offset=1000

Keeping up to date

Rows are ordered by published_at, newest first. To poll for new filings, remember the largest published_at you have seen and pass it as published_after on the next call. New rows never shift the ones you have already read, unlike a bare offset.

GET /holdings?published_after=2026-09-14T08:02:11Z&limit=500

Errors

Errors use standard HTTP status codes and a JSON body with a human-readable detail:

{ "detail": "The Free plan covers NL, ES only; upgrade for DE" }

GET/transactions

Managers' transactions: dealings by persons discharging managerial responsibilities (PDMRs) and their closely associated persons, as published under MAR Article 19 and equivalent national regimes. Newest publication first, paginated.

Query parameters

Example

curl "https://api.duceusapi.com/transactions?country=SE&limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "id": 48211,
      "issuer_id": "iss_01K5APX7Q3S6R2M4V8JH0N3T9E",
      "issuer_name": "Investor AB",
      "issuer_lei": "549300VEBQPHRZBKUX38",
      "country": "SE",
      "person_id": "per_01K5APX8C4T7S3N5W9KJ1P4V0F",
      "person_full_name": "Jane Doe",
      "person_is_anonymized": false,
      "person_role": "CEO",
      "person_position": "Verkställande direktör",
      "is_closely_associated": false,
      "transaction_date": "2026-09-12",
      "transaction_type": "BUY",
      "direction": "ACQUISITION",
      "transaction_type_raw": "Acquisition",
      "instrument": { "isin": "SE0015811963", "kind": "SHARE", "name": null, "ticker": null, "mic": null },
      "instrument_isin": "SE0015811963",
      "instrument_raw": "Aktier",
      "volume": 1500.0,
      "unit_price": 312.4,
      "currency": "SEK",
      "source_name": "fi-insyn",
      "source_reference": "1234567",
      "source_url": "https://marknadssok.fi.se/...",
      "published_at": "2026-09-14T08:02:11Z"
    }
  ],
  "total": 21730,
  "limit": 1,
  "offset": 0
}

Response fields

Each entry of items:

Public ids are opaque strings with a type prefix (iss_ issuers, per_ persons, hld_ holders). They are stable: when two records turn out to be the same entity and are merged, the retired id keeps resolving to the surviving record, whose id the response then carries.

Instrument

GET/holdings

Major shareholding notifications: filings made when a holder's voting rights or capital cross a disclosure threshold (Transparency Directive and equivalents). Newest publication first, paginated.

Query parameters

Example

curl "https://api.duceusapi.com/holdings?country=GB&limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "id": 9034,
      "issuer_id": "iss_01K5APX7Q3S6R2M4V8JH0N3T9E",
      "issuer_name": "Example plc",
      "issuer_lei": "213800EXAMPLE0000001",
      "country": "GB",
      "holder_id": "hld_01K5APX9D5V8T4P6X0KM2Q5W1G",
      "holder_name": "BlackRock Fund Advisors",
      "holder_type": "LEGAL_ENTITY",
      "holder_lei": "549300YOOGP0Y1M95C20",
      "holder_ultimate_parent_lei": "529900VBK42Y5HHRMD23",
      "holder_ultimate_parent_name": "BlackRock, Inc.",
      "event_type": "ACQUISITION",
      "reason_raw": null,
      "event_date": "2026-09-10",
      "notification_date": "2026-09-11",
      "threshold_crossed_pct": 5.0,
      "threshold_direction": "ABOVE",
      "new_pct_voting": 5.12,
      "new_pct_capital": null,
      "new_pct_voting_short": null,
      "new_voting_rights_count": 51200000,
      "prev_pct_voting": 4.97,
      "prev_pct_capital": null,
      "issuer_total_voting_rights": 1000000000,
      "issuer_total_shares": null,
      "is_late": false,
      "supersedes_reference": null,
      "parties": [
        { "holder_id": "hld_01K5APX9D5V8T4P6X0KM2Q5W1G", "name": "BlackRock Fund Advisors", "holder_lei": "549300YOOGP0Y1M95C20", "role": "OBLIGED", "pct_voting": 5.12, "pct_capital": null }
      ],
      "positions": [
        {
          "direction": "LONG",
          "position_kind": "SHARES",
          "holding_basis": "INDIRECT",
          "instrument_isin": "GB00B03MLX29",
          "instrument_type_raw": null,
          "instrument_description": null,
          "count": 51200000,
          "voting_rights_count": 51200000,
          "pct_voting": 5.12,
          "pct_capital": null,
          "expiration": null,
          "exercise_price_raw": null,
          "settlement": null
        }
      ],
      "source_url": "https://www.londonstockexchange.com/...",
      "published_at": "2026-09-11T15:30:00Z"
    }
  ],
  "total": 5402,
  "limit": 1,
  "offset": 0
}

Response fields

Each entry of items:

Party

The first party is always the obliged holder. Further parties describe the ownership chain reported in the filing: controlled undertakings, beneficial owners, members acting in concert.

Position

One entry per instrument line in the filing: plain shares, derivatives, lent stock and so on.

GET/threshold-events

The subset of /holdings that records an actual crossing: filings whose direction the source states as above or below a disclosure line. Filings with an unknown direction are excluded, so every row is a holder entering, leaving or moving between thresholds. Same response shape as /holdings.

Query parameters

Example

New stakes of 5% or more, i.e. likely new significant shareholders:

curl "https://api.duceusapi.com/threshold-events?direction=ABOVE&min_pct=5&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/issuers

Companies with at least one disclosure in either dataset, alphabetically. Use isin or lei to resolve a security to its issuer, or issuer to search by name. Only issuers in countries your plan covers are listed.

Query parameters

Example

curl "https://api.duceusapi.com/issuers?issuer=fugro" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "id": "iss_01K5APX7Q3S6R2M4V8JH0N3T9E",
      "name": "Fugro N.V.",
      "lei": "7245000R8GNBSDTSZ396",
      "legal_name": "Fugro N.V.",
      "jurisdiction": "NL",
      "ultimate_parent_lei": null,
      "ultimate_parent_name": null,
      "countries": ["NL"],
      "instruments": [{ "isin": "NL00150003E1", "kind": "SHARE", "name": null, "ticker": null, "mic": null }],
      "transaction_count": 0,
      "holding_count": 2,
      "latest_published_at": "2026-09-10T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Response fields

Public ids are opaque strings with a type prefix (iss_ issuers, per_ persons, hld_ holders). They are stable: when two records turn out to be the same entity and are merged, the retired id keeps resolving to the surviving record, whose id the response then carries.

GET/issuers/{id}

One issuer, same shape as an entry of /issuers. Returns 404 for an unknown id and 403 when none of the issuer's registers is inside your plan. An id retired by a merge resolves to the surviving issuer.

curl "https://api.duceusapi.com/issuers/iss_01K5APX7Q3S6R2M4V8JH0N3T9E" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/issuers/{id}/shareholders

A derived cap table: for every holder that has ever notified a stake in the issuer, that holder's most recent filing reduced to the fields describing the stake, largest first. Holders whose last filing put them at 0% are dropped.

This is computed from threshold notifications, not reported as such by any register. A holder's stake is only known as of its as_of date; movements that stay between thresholds never trigger a filing and are invisible here. The response is a plain array, not a paginated envelope.

Example

curl "https://api.duceusapi.com/issuers/iss_01K5APX7Q3S6R2M4V8JH0N3T9E/shareholders" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "holder_id": "hld_01K5APX9D5V8T4P6X0KM2Q5W1G",
    "holder_name": "DWS Investment GmbH",
    "holder_type": "UNKNOWN",
    "holder_lei": "549300MJ6B0X7BZ7VZ26",
    "holder_ultimate_parent_lei": "529900IBM3XAY4TH9G96",
    "holder_ultimate_parent_name": "DWS Group GmbH & Co. KGaA",
    "pct_voting": 3.04,
    "pct_capital": 3.04,
    "pct_voting_short": null,
    "voting_rights_count": null,
    "event_type": "OTHER",
    "threshold_direction": "UNKNOWN",
    "as_of": "2026-09-10",
    "published_at": "2026-09-10T00:00:00Z",
    "notification_id": 247,
    "source_url": "https://www.afm.nl/..."
  },
  {
    "holder_id": "hld_01K5APXA0E6W9U5Q7Y1LN3R6X2H",
    "holder_name": "Goldman Sachs Group Inc., The",
    "holder_type": "UNKNOWN",
    "holder_lei": "784F5XWPLTWKTBV3E584",
    "holder_ultimate_parent_lei": null,
    "holder_ultimate_parent_name": null,
    "pct_voting": 3.03,
    "pct_capital": 3.03,
    "pct_voting_short": 2.52,
    "voting_rights_count": null,
    "event_type": "OTHER",
    "threshold_direction": "UNKNOWN",
    "as_of": "2026-09-10",
    "published_at": "2026-09-10T00:00:00Z",
    "notification_id": 245,
    "source_url": "https://www.afm.nl/..."
  }
]

Response fields

GET/issuers/{id}/shareholder-groups

The same cap table rolled up by ultimate parent: every holder that GLEIF says is consolidated by the same group becomes one line with its members listed, so the dozens of “BlackRock …” entities read as one shareholder. Holders without a known parent are their own group. Plain array, largest first.

curl "https://api.duceusapi.com/issuers/iss_01K5APX7Q3S6R2M4V8JH0N3T9E/shareholder-groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

GET/issuers/{id}/timeline

Every disclosure about one issuer (managers' transactions and shareholding notifications merged), newest publication first. Same item shape and paging as /feed.

curl "https://api.duceusapi.com/issuers/iss_01K5APX7Q3S6R2M4V8JH0N3T9E/timeline?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/persons

Named managers (PDMRs) and closely associated persons with at least one transaction you may see, as identities: one entry per person with every issuer they have dealt at. Anonymised persons are excluded.

Query parameters

Example

curl "https://api.duceusapi.com/persons?q=qviberg" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "id": "per_01K5APX8C4T7S3N5W9KJ1P4V0F",
      "full_name": "Johan Qviberg",
      "is_anonymized": false,
      "mandates": [
        {
          "issuer_id": "iss_01K5APX7Q3S6R2M4V8JH0N3T9E",
          "issuer_name": "Investment AB Öresund",
          "role": "BOARD_MEMBER",
          "position": "Styrelseledamot",
          "is_closely_associated": false,
          "first_seen": "2024-03-12",
          "last_seen": "2026-08-30",
          "transaction_count": 14
        }
      ],
      "linked_holders": [],
      "transaction_count": 14,
      "latest_published_at": "2026-09-01T07:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Response fields

Mandate

GET/persons/{id}

One person, same shape as an entry of /persons. /persons/{id}/transactions lists their deals across every mandate, newest publication first, with the same item shape and paging as /transactions.

curl "https://api.duceusapi.com/persons/per_01K5APX8C4T7S3N5W9KJ1P4V0F/transactions?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/holders

Parties that have notified a major holding you may see: funds, banks, holding companies and individuals. Where a holder has been confirmed to be the same individual as a PDMR, linked_persons carries that identity, joining the two datasets.

Query parameters

Example

curl "https://api.duceusapi.com/holders?ultimate_parent_lei=529900VBK42Y5HHRMD23" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

GET/holders/{id}

One holder with positions: its latest notification in each issuer, largest stake first. /holders/{id}/timeline merges the holder's own notifications with every transaction of a linked PDMR identity, with the same item shape and paging as /feed.

curl "https://api.duceusapi.com/holders/hld_01K5APX9D5V8T4P6X0KM2Q5W1G" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/feed

Both datasets in one stream ordered by published_at, for clients that would otherwise poll /transactions and /holdings in lockstep. Each item carries a few common fields plus the full row under transaction or holding, depending on kind.

Query parameters

Example

curl "https://api.duceusapi.com/feed?published_after=2026-09-15T09:00:00Z&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "kind": "holding",
      "id": 39,
      "issuer_id": "iss_01K5APX7Q3S6R2M4V8JH0N3T9E",
      "issuer_name": "J SAINSBURY PLC",
      "country": "GB",
      "event_date": "2026-09-11",
      "published_at": "2026-09-15T12:00:00Z",
      "transaction": null,
      "holding": { ... }
    },
    {
      "kind": "transaction",
      "id": 1087,
      "issuer_id": "iss_01K5APXB1F7X0V6R8Z2MP4S7Y3J",
      "issuer_name": "Investor AB",
      "country": "SE",
      "event_date": "2026-09-12",
      "published_at": "2026-09-15T11:58:00Z",
      "transaction": { ... },
      "holding": null
    }
  ],
  "total": 1357,
  "limit": 500,
  "offset": 0
}

Item fields

Deep offset paging over the feed is slower than over a single dataset; prefer published_after for keeping up to date.

GET/coverage

What the archive holds per register and dataset, whole history. Plan limits are reported (in_plan), not applied, so you can see what an upgrade would add. Plain array.

curl "https://api.duceusapi.com/coverage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

GET/health

Unauthenticated liveness check. Returns:

{ "status": "ok" }

Enumerations

All enumerated fields are upper-case strings. New values may be added; treat unknown ones as OTHER.