> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rangler.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies and dividends fields

> Definitions, types, allowed values, and defaults for companies and dividends.

Use this reference with the endpoint documentation. A required field must be present; a nullable field can still contain `null`. Missing data does not mean zero. See [Field guide](/field-guide) for unit and status conventions.

### `GET /v1/companies`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `q` | query | string or null | optional | Search by ticker or name |
| `sector` | query | string or null | optional | Filter by the company's stored sector label. |
| `index` | query | string or null | optional | Filter by index membership |
| `exchange` | query | string or null | optional | Filter by primary exchange (e.g., NGX, NASD) |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `50`. |
| `country_code` | query | string or null | optional | Filter by ISO 3166-1 alpha-2 market country code |

### `GET /v1/companies/{company_id}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |

### `GET /v1/companies/{company_id}/meeting-media`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `status` | query | array of string or null | optional | Filter by media status |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `12`. |

### `GET /v1/companies/{company_id}/details`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |

### `GET /v1/companies/{company_id}/dividends`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `100`. |
| `yield_as_of` | query | string (date) or null | optional | Date used for the YTD dividend-yield summary; defaults to the latest available price. |

<a id="companies-page" />

## Companies page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Company](/fields/companies#company-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `next_cursor` | string or null | optional | Opaque cursor for the next page. Pass it unchanged as cursor; null means no next page. |

<a id="company-auditor" />

## Company auditor

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `name` | string or null | optional | Display name of the identified resource. |

<a id="company-details" />

## Company details

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `asset_type` | string | optional | Resource category: company for an issuer or fund for a linked fund security. Allowed values: `company`, `fund`. Default: `"company"`. |
| `symbol` | string | required | Trading symbol of the security. |
| `name` | string | required | Display name of the identified resource. |
| `is_public` | boolean or null | optional | Whether Rangler includes the company in its public-company directory. False excludes it from company list/search; an ID lookup can still return it. This flag does not distinguish delisted, suspended, or private companies. |
| `exchange` | string or null | optional | Exchange or trading venue code, such as NGX or NASD. |
| `country_code` | string | optional | Two-letter ISO 3166-1 country code identifying the market, such as NG. Default: `"NG"`. |
| `board` | string or null | optional | Exchange listing board when known; not the company's board of directors. |
| `sector` | string or null | optional | Industry sector assigned to the company, when known. |
| `year_end` | string or null | optional | Issuer's financial year-end label when known. |
| `incorporated_on` | string (date) or null | optional | Company incorporation date when known. |
| `listed_on` | string (date) or null | optional | Date the company was listed when known. This is not a delisting date. |
| `website` | string or null | optional | Website associated with the resource. |
| `email` | string or null | optional | Published contact email address for the company. |
| `phone` | string or null | optional | Published contact phone number for the company. |
| `registered_office` | string or null | optional | Published address of the company's registered office. |
| `registrar` | [Company registrar](/fields/companies#company-registrar) or null | optional | Share registrar's name and website when known. |
| `auditor` | [Company auditor](/fields/companies#company-auditor) or null | optional | External auditor's name when known. |
| `company_secretary` | string or null | optional | Published name of the company secretary when known. |
| `employee_count` | integer or null | optional | Reported number of employees; null means unavailable. |
| `share_info` | [Company share info](/fields/companies#company-share-info) or null | optional | Share count, free float, price, and market-capitalization observations with their currencies and date. |
| `officers` | array of [Company officer](/fields/companies#company-officer) or null | optional | Company officers and their roles when available. |
| `links` | [Company links](/fields/companies#company-links) or null | optional | External company profile links. |
| `documents` | array of [Company document summary](/fields/companies#company-document-summary) or null | optional | Available documents associated with this company or linked fund. |
| `fund` | [Company linked fund summary](/fields/companies#company-linked-fund-summary) or null | optional | Linked fund identity when asset\_type is fund; otherwise null. |
| `summary` | string or null | optional | Short description of the event, document, or resource. |
| `last_fetched_at` | string (date-time) or null | optional | Timestamp of the latest stored profile or market-source retrieval used for these details. |
| `source` | string or null | optional | Provider or source label for the returned company information. |

<a id="company-dividend-read" />

## Company dividend

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `dividend_type` | string or null | optional | Disclosed dividend category, such as interim or final, when known. |
| `status` | string or null | optional | Dividend lifecycle label: proposed, declared, revised, approved, paid, or cancelled when known. |
| `declaration_date` | string (date) or null | optional | Date the dividend was declared or announced. |
| `qualification_date` | string (date) or null | optional | Date shareholders must qualify for the dividend. |
| `agm_approval_date` | string (date) or null | optional | Date of the AGM associated with dividend approval when known. |
| `closure_start_date` | string (date) or null | optional | First day of the share-register closure period. |
| `closure_end_date` | string (date) or null | optional | Last day of the share-register closure period. |
| `payment_date` | string (date) or null | optional | Announced dividend payment date when known; not proof that payment occurred. |
| `gross` | number or null | optional | Gross dividend per share before tax, in currency. |
| `currency` | string or null | optional | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `gross_converted` | number or null | optional | Gross per share converted to the listing market currency on the declaration date. |
| `gross_converted_currency` | string or null | optional | Currency of gross\_converted. |
| `gross_conversion_rate` | number or null | optional | Multiplier applied to gross to produce gross\_converted. |
| `gross_conversion_rate_date` | string (date) or null | optional | Date of the exchange-rate observation used for the dividend conversion. |
| `fiscal_year` | integer or null | optional | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `period_end_date` | string (date) or null | optional | Closing date of the reporting period. |
| `yield_pct` | number or null | optional | Dividend yield in percentage points: 5 means 5%; not the fractional format used by chart changes. |
| `yield_currency` | string or null | optional | Common currency used for the dividend and share price in the yield calculation. |
| `yield_fx_rate` | number or null | optional | Exchange-rate multiplier used to align the dividend and price currencies for yield. |
| `yield_fx_rate_date` | string (date) or null | optional | Date of the exchange rate used in the yield calculation. |
| `source_ref` | string or null | optional | Source reference linking the dividend to its supporting evidence. |
| `filing_id` | string (uuid) or null | optional | Stable Rangler identifier of the source filing. |
| `filing_title` | string or null | optional | Title of the source filing. |
| `filing_url` | string or null | optional | URL of the source filing. |
| `source_page` | string or null | optional | Page reference in the source document, as provided by the source. |
| `source_excerpt` | string or null | optional | Text excerpt supporting the extracted value or event. |
| `revision_number` | integer | optional | Revision number of this dividend record. Default: `0`. |
| `sources` | array of [Company dividend source](/fields/companies#company-dividend-source-read) | optional | Evidence or source references supporting the returned information. |
| `revisions` | array of [Company dividend revision](/fields/companies#company-dividend-revision-read) | optional | Earlier values or changes, with their dates and source references. |

<a id="company-dividend-revision-read" />

## Company dividend revision

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `revision_number` | integer | required | Revision number of this dividend record. |
| `changed_fields` | array of string | required | Field names changed by this revision. |
| `recorded_at` | string (date-time) | required | Timestamp when Rangler recorded this revision. |

<a id="company-dividend-source-read" />

## Company dividend source

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `source_kind` | string | required | Category of the source record used as evidence. |
| `source_ref` | string | required | Source reference linking the dividend to its supporting evidence. |
| `filing_id` | string (uuid) or null | optional | Stable Rangler identifier of the source filing. |
| `filing_title` | string or null | optional | Title of the source filing. |
| `filing_url` | string or null | optional | URL of the source filing. |
| `source_page` | string or null | optional | Page reference in the source document, as provided by the source. |
| `source_excerpt` | string or null | optional | Text excerpt supporting the extracted value or event. |
| `source_published_at` | string (date-time) or null | optional | Publication timestamp reported for the underlying source. |

<a id="company-dividend-yield-summary-read" />

## Company dividend yield summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `period` | string | optional | Summary window label; YTD means year to date. Default: `"YTD"`. |
| `year` | integer | required | Calendar year used by this response. |
| `as_of_date` | string (date) | required | Calendar date to which these observations or values apply. |
| `price_date` | string (date) | required | Date of the share price used in the yield calculation. |
| `total_gross` | number | required | Sum of eligible gross dividends per share for the selected year in currency. |
| `currency` | string | required | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `price` | number | required | Share price used in the dividend yield calculation, in currency. |
| `yield_pct` | number | required | Dividend yield in percentage points: 5 means 5%; not the fractional format used by chart changes. |
| `included_dividend_count` | integer | required | Number of dividends included in the year-to-date yield. |
| `converted_dividend_count` | integer | optional | Number of included dividends requiring currency conversion. Default: `0`. |
| `excluded_dividend_count` | integer | optional | Dividend count excluded because an amount or required conversion was unavailable. Default: `0`. |

<a id="company-dividends-page" />

## Company dividends page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Company dividend](/fields/companies#company-dividend-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `ytd_yield` | [Company dividend yield summary](/fields/companies#company-dividend-yield-summary-read) or null | optional | Year-to-date dividend yield summary, including price date and dividend inclusion counts. |

<a id="company-document-summary" />

## Company document summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `type` | string | required | Document category, such as fund\_factsheet. |
| `format` | string | required | Response or document format; its allowed values are shown in the field schema. |
| `url` | string | required | URL of the source document, article, or resource. |
| `title` | string or null | optional | Human-readable title of the resource or source document. |
| `as_of_date` | string (date) or null | optional | Calendar date to which these observations or values apply. |
| `published_at` | string (date-time) or null | optional | Publication timestamp of the source document or article when known. |

<a id="company-linked-fund-summary" />

## Company linked fund summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `provider` | string | required | Stable identifier of the linked fund manager or data provider. |
| `slug` | string | required | URL-friendly identifier for the linked fund. |
| `ticker` | string or null | optional | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `name` | string | required | Display name of the identified resource. |
| `category` | string or null | optional | Fund investment category when known. |
| `base_currency` | string or null | optional | Primary currency in which the fund is denominated. |

<a id="company-links" />

## Company links

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `company_profile_page` | string or null | optional | Exchange company-profile page URL. |

<a id="company-meeting-media-page" />

## Company meeting media page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Company meeting media](/fields/companies#company-meeting-media-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `count` | integer | required | Number of records or observations returned in this response. |

<a id="company-meeting-media-read" />

## Company meeting media

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `platform` | string | required | Hosting platform of the meeting stream or recording. |
| `source_type` | string or null | optional | Kind of source through which the meeting media was discovered. |
| `channel_name` | string or null | optional | Hosting channel's display name when available. |
| `channel_url` | string or null | optional | URL of the hosting channel when available. |
| `video_url` | string | required | URL of the meeting stream or recording. |
| `title` | string | required | Human-readable title of the resource or source document. |
| `description_snippet` | string or null | optional | Excerpt of the media's source description. |
| `meeting_type` | string or null | optional | Meeting category identified from the media, such as AGM or results presentation. |
| `live_status` | string or null | optional | Hosting platform's live/broadcast status when available; separate from Rangler's media\_status. |
| `media_status` | string | required | Media lifecycle: live, upcoming, replay\_available, unknown, or stale\_upcoming. stale\_upcoming means a previously scheduled broadcast has not been confirmed as live or replayable. |
| `scheduled_start_at` | string or null | optional | Scheduled starting timestamp of the stream when known. |
| `published_at` | string or null | optional | Publication timestamp of the source document or article when known. |
| `duration_seconds` | integer or null | optional | Duration of the available recording in seconds. |
| `view_count` | integer or null | optional | Source-reported view count at the time of collection. |
| `thumbnail_url` | string or null | optional | URL of the media's preview image. |

<a id="company-officer" />

## Company officer

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `role` | string | required | Published role or position held by the person. |
| `name` | string | required | Display name of the identified resource. |

<a id="company-read" />

## Company

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `name` | string | required | Display name of the identified resource. |
| `ticker` | string | required | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `isin` | string or null | optional | International Securities Identification Number of the security when known. |
| `sector` | string or null | optional | Industry sector assigned to the company, when known. |
| `is_public` | boolean or null | optional | Whether Rangler includes the company in its public-company directory. False excludes it from company list/search; an ID lookup can still return it. This flag does not distinguish delisted, suspended, or private companies. |
| `exchange` | string or null | optional | Exchange or trading venue code, such as NGX or NASD. |
| `country_code` | string | optional | Two-letter ISO 3166-1 country code identifying the market, such as NG. Default: `"NG"`. |
| `market_classification` | string or null | optional | Exchange listing classification, such as Main Board; not a trading or listing-status flag. |
| `index_memberships` | array of string or null | optional | Market index names or codes associated with the company. |
| `ir_url` | string or null | optional | URL of the company's investor-relations website. |
| `website` | string or null | optional | Website associated with the resource. |
| `logo_url` | string or null | optional | URL of the resource's logo when available. |
| `created_at` | string (date-time) or null | optional | Timestamp when Rangler created this record; not the source publication time. |

<a id="company-registrar" />

## Company registrar

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `name` | string or null | optional | Display name of the identified resource. |
| `website` | string or null | optional | Website associated with the resource. |

<a id="company-share-info" />

## Company share info

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `shares_outstanding` | integer or null | optional | Number of outstanding shares, expressed as a count. |
| `free_float` | number or null | optional | Free-float share percentage: 25 means 25%, not 0.25. |
| `last_price` | number or null | optional | Latest stored price in last\_price\_currency; it is not guaranteed to be a live quote. |
| `last_price_currency` | string or null | optional | Currency of last\_price. |
| `market_cap_usd_m` | number or null | optional | Market capitalization expressed in millions of US dollars. |
| `market_cap_value` | number or null | optional | Numeric market capitalization in base units of market\_cap\_currency. |
| `market_cap_currency` | string or null | optional | Currency of the market-capitalization amount. |
| `market_cap_display` | string or null | optional | Formatted market-capitalization label. Use numeric fields for calculations. |
| `snapshot_date` | string (date) or null | optional | Date of the market observation used for the returned share information. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.