> ## 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 Summary

> Aggregated director-dealings data for a single NGX-listed company.

Returns aggregated data from the available director-dealings records for a company, including buy and sell totals, trailing 90-day activity, monthly trends, per-insider breakdowns, and filing lag. The summary is computed from the same records returned by [`GET /companies/{symbol}/director-dealings`](/api-reference/companies/director-dealings), so you don't need to download and aggregate each filing yourself.

This endpoint requires a Pro plan or higher.

Returns `404` if the company has no director-dealings filings on record.

<CodeGroup>
  ```bash Summary for UCAP theme={null}
  curl "https://api.ngnmarket.com/v1/companies/UCAP/director-dealings/summary" \
    -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/summary`,
    { 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/summary',
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

`filing_lag` groups filings by the number of days between the transaction date and the NGX disclosure date. The current buckets are `0_5_days`, `6_14_days`, and `15_plus_days`.

<Note>
  These are NGN Market grouping labels based on elapsed time and should not be interpreted as a regulatory compliance determination.
</Note>


## OpenAPI

````yaml GET /companies/{symbol}/director-dealings/summary
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/summary:
    get:
      tags:
        - Companies
      summary: Director dealings summary
      description: >
        Returns aggregated data from the available director-dealings records for
        a company: totals across the available records plus trailing 90-day
        totals, monthly trend, per-insider breakdown, and filing lag. The
        summary is computed from the same records returned by `GET
        /companies/{symbol}/director-dealings`, so you don't need to download
        and aggregate each filing yourself.


        **Plan required:** Pro
      operationId: getCompanyDirectorDealingsSummary
      parameters:
        - name: symbol
          in: path
          required: true
          description: NGX ticker symbol (e.g. `GTCO`). Case-insensitive.
          schema:
            type: string
            example: UCAP
      responses:
        '200':
          description: Summary retrieved successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DirectorDealingsSummary'
              examples:
                ucapSummary:
                  summary: Insider trading summary for UCAP
                  value:
                    success: true
                    data:
                      total: 684
                      buy_count: 511
                      sell_count: 173
                      buy_value: 1196639493.25
                      sell_value: 242116085.61
                      net_value: 954523407.64
                      buy_value_90d: 151399399.2
                      sell_value_90d: 365220.35
                      net_value_90d: 151034178.85
                      avg_days_to_file: 2.87
                      oldest: '2020-03-05'
                      newest: '2026-08-17'
                      largest:
                        insider_name: ARTROL INVESTMENT COMPANY LIMITED
                        insider_position: RELATED PARTY TO PETER ASHADE
                        transaction_type: purchase
                        total_value: 175030000
                        transaction_date_from: '2024-11-11'
                      top_insider:
                        name: ARTROL INVESTMENT COMPANY LIMITED
                        total_value: 88938440.6
                        trades: 3
                      monthly:
                        - month_start: '2026-07-01'
                          buy_value: 22000000
                          sell_value: 4200000
                          buy_count: 6
                          sell_count: 2
                          net_value: 17800000
                      insiders:
                        - name: ARTROL INVESTMENT COMPANY LIMITED
                          position: RELATED PARTY TO PETER ASHADE
                          insider_type: related_party
                          buy_value: 88938440.6
                          sell_value: 0
                          net_value: 88938440.6
                          buy_count: 3
                          sell_count: 0
                          total_trades: 3
                          last_trade_date: '2024-11-11'
                      filing_lag:
                        0_5_days: 640
                        6_14_days: 31
                        15_plus_days: 13
                        max_days: 62
                        min_days: 0
                    meta:
                      plan: pro
                      calls_used: 119
                      calls_remaining: 249881
                      reset_at: '2026-10-01T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: No director-dealings data found for this symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: No director-dealings data found for 'UNKNOWN'.
        '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'
    DirectorDealingsSummary:
      type: object
      description: Aggregated director-dealings data for a single NGX-listed company.
      properties:
        total:
          type: integer
        buy_count:
          type: integer
        sell_count:
          type: integer
        buy_value:
          type: number
        sell_value:
          type: number
        net_value:
          type: number
        buy_value_90d:
          type: number
        sell_value_90d:
          type: number
        net_value_90d:
          type: number
        avg_days_to_file:
          type: number
          nullable: true
        oldest:
          type: string
          format: date
          nullable: true
        newest:
          type: string
          format: date
          nullable: true
        largest:
          type: object
          nullable: true
          properties:
            insider_name:
              type: string
            insider_position:
              type: string
              nullable: true
            transaction_type:
              type: string
            total_value:
              type: number
            transaction_date_from:
              type: string
              format: date
        top_insider:
          type: object
          nullable: true
          properties:
            name:
              type: string
            total_value:
              type: number
            trades:
              type: integer
        monthly:
          type: array
          items:
            type: object
            properties:
              month_start:
                type: string
                format: date
              buy_value:
                type: number
              sell_value:
                type: number
              buy_count:
                type: integer
              sell_count:
                type: integer
              net_value:
                type: number
        insiders:
          type: array
          description: >-
            Per-insider breakdown across the available records for this company,
            ranked by net value.
          items:
            type: object
            properties:
              name:
                type: string
              position:
                type: string
                nullable: true
              insider_type:
                type: string
                nullable: true
              buy_value:
                type: number
              sell_value:
                type: number
              net_value:
                type: number
              buy_count:
                type: integer
              sell_count:
                type: integer
              total_trades:
                type: integer
              last_trade_date:
                type: string
                format: date
                nullable: true
        filing_lag:
          type: object
          description: >-
            Groups filings by elapsed days between the transaction date and the
            NGX disclosure date. These are NGN Market grouping labels based only
            on elapsed time, not a regulatory compliance determination.
          properties:
            0_5_days:
              type: integer
              description: Filed 0-5 days after the transaction.
            6_14_days:
              type: integer
              description: Filed 6-14 days after the transaction.
            15_plus_days:
              type: integer
              description: Filed more than 14 days after the transaction.
            max_days:
              type: integer
              nullable: true
            min_days:
              type: integer
              nullable: true
    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.
    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'
  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 <key>'
            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).

````