> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngnmarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Director Dealings
> Structured director-dealings filings for a single NGX-listed company.
Returns structured director-dealings filings available for a single NGX-listed company. NGX publishes these as PDF letters, and this endpoint extracts the insider identity, transaction type, volume, price, value, tranche breakdown, and filing-timeliness data into structured fields.
This is different from [`GET /companies/{symbol}/disclosures?category=director_dealings`](/api-reference/companies/disclosures), which returns only the filing envelope such as the title, PDF link, and date.
Every row also includes `price_at_txn` (the closing price on the transaction date) and `current_price`, so you can see how the share price has moved since the transaction without making another request.
This endpoint requires a Pro plan or higher. Pro includes the 50 most recent filings per company. Business and Enterprise include the full available history in our dataset.
Coverage is partial, so an empty result does not necessarily mean there has been no director-dealings activity.
```bash All dealings for UCAP theme={null}
curl "https://api.ngnmarket.com/v1/companies/UCAP/director-dealings" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```bash Buys over ₦10m only theme={null}
curl "https://api.ngnmarket.com/v1/companies/UCAP/director-dealings?side=buy&minValue=10000000" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```javascript JavaScript theme={null}
const symbol = 'UCAP';
const res = await fetch(
`https://api.ngnmarket.com/v1/companies/${symbol}/director-dealings?side=buy`,
{ headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } }
);
const { data } = await res.json();
```
```python Python theme={null}
import requests
symbol = 'UCAP'
res = requests.get(
f'https://api.ngnmarket.com/v1/companies/{symbol}/director-dealings',
params={'side': 'buy', 'minValue': 10000000},
headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
)
data = res.json()['data']
```
`insider_type` preserves the classification available in the filing, with values such as `executive_director`, `senior_officer`, `employee`, and `connected_to_director`. The `insider` filter groups these into broader buckets such as `directors`, `executives`, `employees`, `connected`, `shareholders`, and `other`, so you can filter without knowing every raw value.
Use `insider_type` directly when the distinction between those classifications matters for your analysis.
## OpenAPI
````yaml GET /companies/{symbol}/director-dealings
openapi: 3.1.0
info:
title: NGN Market API
version: '1.0'
description: >
The NGN Market API provides programmatic access to Nigerian Exchange Group
(NGX) market data, including equities, forex rates, company profiles,
indices, bonds, and financial news.
## Base URL
All endpoints are served from:
```
https://api.ngnmarket.com/v1
```
## Authentication
Every request requires a Bearer token in the `Authorization` header:
```
Authorization: Bearer ngm_live_YOUR_KEY
```
Generate and manage your API keys from the [developer
dashboard](https://ngnmarket.com/developer).
## Plans & Quotas
| Plan | Monthly Calls | Requests/min | Price |
| :--- | ---: | ---: | :--- |
| Free | 3,000 | 30 | Free |
| Hobby | 10,000 | 60 | ₦15,000/mo |
| Starter | 100,000 | 120 | ₦50,000/mo |
| Pro | 250,000 | 120 | ₦100,000/mo |
| Business | 2,000,000 | 300 | ₦300,000/mo |
| Enterprise | Unlimited | Unlimited | Custom |
Every response includes a `meta` object showing your current usage and
remaining quota. Exceeding the per-minute rate limit returns `429
RATE_LIMITED`. Exceeding the monthly quota returns `429 QUOTA_EXCEEDED`.
## Response Envelope
All responses use a consistent JSON envelope:
```json
{
"success": true,
"data": { ... },
"meta": {
"plan": "starter",
"calls_used": 4821,
"calls_remaining": 95179,
"reset_at": "2026-05-15T23:57:00.000Z"
}
}
```
contact:
name: NGN Market Support
email: support@ngnmarket.com
url: https://ngnmarket.com
license:
name: Proprietary
servers:
- url: https://api.ngnmarket.com/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Market
description: >-
Daily market snapshots, top trades, movers, market breadth, sectors, and
YTD performers.
- name: Companies
description: >-
Browse, search, and retrieve profiles, price charts, and financial
statements for NGX-listed companies.
- name: Forex
description: Current and historical NGN exchange rates against major currencies.
- name: Indices
description: >-
All NGX market indices, including list, detail with constituents, and
historical chart data.
- name: ETFs
description: >-
NGX-listed Exchange Traded Funds and ETPs — list, full fund detail, and
historical daily price data.
- name: Bonds
description: >-
NGX-listed bond instruments with issuer details, coupon rates, and
maturity dates.
- name: Disclosures
description: >-
Official corporate filings from NGX-listed companies (financial
statements, AGM notices, board meetings, director dealings, earnings
forecasts). Sourced from NGX Group and updated twice daily.
- name: Insiders
description: >-
Structured director-dealings data extracted from NGX PDMR filings.
Per-company and market-wide feeds, aggregated data, and cluster detection
for insiders trading the same symbol and direction within a window.
Distinct from the raw `/disclosures` feed, which only returns filing
metadata.
- name: Blog
description: >-
Published NGN Market blog posts. List, search, and filter by category or
company.
- name: Dividends
description: >-
Market-wide NGX dividend calendar. Browse upcoming and recently paid
dividends across all listed companies with optional search and pagination.
- name: Account
description: >-
Quota status, 30-day request analytics, and paginated request logs for the
authenticated user.
paths:
/companies/{symbol}/director-dealings:
get:
tags:
- Companies
summary: Director dealings by company
description: >
Returns structured director-dealings filings available for a single
NGX-listed company. NGX publishes these as PDF letters, and this
endpoint extracts the insider identity, transaction type, volume, price,
value, tranche breakdown, and filing-timeliness data into structured
fields.
This is different from `GET
/companies/{symbol}/disclosures?category=director_dealings`, which
returns only the filing envelope such as the title, PDF link, and date.
Every row also carries `price_at_txn` (the closing price on the
transaction date) and `current_price`, so you can see how the share
price has moved since the transaction without making another request.
**Plan required:** Pro. Pro includes the 50 most recent filings per
company. Business and Enterprise include the full available history in
our dataset.
Coverage is partial, so an empty result does not necessarily mean there
has been no director-dealings activity.
operationId: getCompanyDirectorDealings
parameters:
- name: symbol
in: path
required: true
description: NGX ticker symbol (e.g. `GTCO`). Case-insensitive.
schema:
type: string
example: UCAP
- name: side
in: query
description: Filter by transaction direction.
schema:
type: string
enum:
- buy
- sell
- name: insider
in: query
description: Filter by insider-type bucket.
schema:
type: string
enum:
- directors
- executives
- employees
- connected
- shareholders
- other
- name: minValue
in: query
description: Minimum transaction value in NGN.
schema:
type: number
example: 10000000
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: >-
Results per page. Pro's true cap is 50 total rows regardless of
paging.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
responses:
'200':
description: Director dealings retrieved successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DirectorDealing'
pagination:
$ref: '#/components/schemas/PaginationExtended'
examples:
ucapDealings:
summary: Recent UCAP director dealings
value:
success: true
data:
data:
- id: 281
disclosure_id: 2261
company_symbol: UCAP
company_name: UNITED CAPITAL PLC
insider_name: OYEBODE ISAAC BAYONLE
insider_slug: oyebode-isaac-bayonle
insider_position: Team Member, Internal Control.
insider_type: employee
is_corporate_insider: false
notification_type: initial
transaction_type: sale
side: sell
is_open_market: true
acquired_or_disposed: D
instrument_type: ordinary_shares
total_volume: 3651
average_price: 17.85
total_value: 65170.35
total_value_reported: null
currency: NGN
shares_owned_after: null
shares_owned_after_source: null
letter_date: '2026-08-18'
transaction_date_from: '2026-08-17'
transaction_date_to: null
date_suspect: false
place_of_transaction: NIGERIA
days_to_file: 2
days_letter_to_disclosure: 1
tranche_count: 1
tranches:
- volume: 3651
price: 17.85
price_low: null
price_high: null
date: '2026-08-18'
is_scanned: false
extraction_confidence: high
extraction_notes: null
document_url: >-
https://doclib.ngxgroup.com/Financial_NewsDocs/176_SIGNED_-_NOTICE_OF_INSIDER_DEALING_-_SALE_-_OYEBODE_ISAAC_BAYONLE-19.08.2026.pdf
disclosure_title: UNITED CAPITAL PLC DIRECTORSDEALINGS
disclosed_at: '2026-08-19'
price_at_txn: null
current_price: 18.6
pagination:
page: 1
limit: 25
total: 25
true_total: 684
locked_rows: 25
pages: 2
has_next: true
has_prev: false
meta:
plan: pro
calls_used: 118
calls_remaining: 249882
reset_at: '2026-10-01T00:00:00.000Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/PlanRequired'
'429':
$ref: '#/components/responses/QuotaExceeded'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
SuccessEnvelope:
type: object
required:
- success
properties:
success:
type: boolean
const: true
meta:
$ref: '#/components/schemas/Meta'
DirectorDealing:
type: object
description: >-
A single structured director-dealings filing, extracted from an NGX PDMR
disclosure PDF.
properties:
id:
type: integer
disclosure_id:
type: integer
description: Foreign key to the underlying corporate_disclosures filing.
company_symbol:
type: string
company_name:
type: string
insider_name:
type: string
insider_slug:
type: string
description: >-
Stable, normalised identifier for this insider. Collapses
name-spelling variants, e.g. "MR. X" and "X", to one identity.
insider_position:
type: string
nullable: true
insider_type:
type: string
description: >-
Raw taxonomy value. Belongs to one of the insider-type buckets used
by the `insider` filter (directors, executives, employees,
connected, shareholders, other).
example: executive_director
is_corporate_insider:
type: boolean
notification_type:
type: string
nullable: true
transaction_type:
type: string
description: >-
Raw taxonomy value (e.g. `purchase`, `sale`,
`staff_scheme_purchase`).
side:
type: string
enum:
- buy
- sell
- other
description: Derived classification of transaction_type.
is_open_market:
type: boolean
acquired_or_disposed:
type: string
nullable: true
instrument_type:
type: string
nullable: true
total_volume:
type: number
nullable: true
average_price:
type: number
nullable: true
description: NGN, unless currency is set.
total_value:
type: number
nullable: true
total_value_reported:
type: number
nullable: true
currency:
type: string
example: NGN
shares_owned_after:
type: number
nullable: true
shares_owned_after_source:
type: string
nullable: true
letter_date:
type: string
format: date
nullable: true
transaction_date_from:
type: string
format: date
nullable: true
transaction_date_to:
type: string
format: date
nullable: true
date_suspect:
type: boolean
description: >-
True when the extraction pipeline flagged this filing's date as
unreliable.
place_of_transaction:
type: string
nullable: true
days_to_file:
type: integer
nullable: true
description: Days between the transaction date and the NGX filing date.
days_letter_to_disclosure:
type: integer
nullable: true
tranche_count:
type: integer
tranches:
type: array
description: >-
Per-tranche volume/price/date breakdown, when the filing reports the
transaction in multiple tranches.
items:
type: object
properties:
volume:
type: number
nullable: true
price:
type: number
nullable: true
price_low:
type: number
nullable: true
price_high:
type: number
nullable: true
date:
type: string
format: date
nullable: true
is_scanned:
type: boolean
description: >-
True if the source filing was a scanned image rather than
machine-readable text.
extraction_confidence:
type: string
nullable: true
enum:
- high
- medium
- low
extraction_notes:
type: string
nullable: true
document_url:
type: string
description: Direct URL to the source PDF on the NGX document library.
disclosure_title:
type: string
disclosed_at:
type: string
format: date
price_at_txn:
type: number
nullable: true
description: Closing price on transaction_date_from.
current_price:
type: number
nullable: true
description: Latest known price for the company.
PaginationExtended:
type: object
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 20
total:
type: integer
example: 42
pages:
type: integer
example: 3
has_next:
type: boolean
example: true
has_prev:
type: boolean
example: false
Meta:
type: object
description: Quota and plan metadata included on every authenticated response.
properties:
plan:
type: string
description: Current plan name.
enum:
- free
- hobby
- starter
- pro
- business
- enterprise
example: starter
calls_used:
type: integer
description: Total calls made this calendar month across all your keys.
example: 4821
calls_remaining:
type: integer
description: Calls remaining before your quota is exhausted.
example: 95179
reset_at:
type: string
format: date-time
description: >-
ISO 8601 UTC timestamp of your next quota reset (your account's
billing renewal date, not the calendar month start).
example: '2026-06-15T23:57:00.000Z'
ErrorEnvelope:
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error identifier.
example: NOT_FOUND
message:
type: string
description: Human-readable error description.
example: Resource not found.
required_plan:
type: string
description: _(PLAN_REQUIRED only)_ Minimum plan needed.
current_plan:
type: string
description: _(PLAN_REQUIRED only)_ Your current plan.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
missingKey:
summary: Missing Authorization header
value:
success: false
error:
code: MISSING_API_KEY
message: 'Provide your API key via: Authorization: Bearer '
invalidKey:
summary: Invalid or revoked key
value:
success: false
error:
code: INVALID_API_KEY
message: API key not found or revoked.
PlanRequired:
description: Endpoint requires a higher plan.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PLAN_REQUIRED
message: This endpoint requires a starter plan or higher.
required_plan: starter
current_plan: free
QuotaExceeded:
description: Monthly call limit reached.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorEnvelope'
- type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
example:
success: false
error:
code: QUOTA_EXCEEDED
message: >-
Monthly call limit of 100,000 reached. Resets on
2026-05-01T00:00:00.000Z.
meta:
plan: starter
calls_used: 100000
calls_remaining: 0
reset_at: '2026-05-15T23:57:00.000Z'
ServerError:
description: Unexpected server-side failure. Safe to retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: SERVER_ERROR
message: Something went wrong on our end. Please try again.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: ngm_live_*
description: >
Pass your API key as a Bearer token: `Authorization: Bearer
ngm_live_YOUR_KEY`.
Generate keys at
[ngnmarket.com/dashboard/developer](https://ngnmarket.com/developer).
````