--- title: "Fundamentals Layer API" url: "https://developer.argaam.com/apis/fundamentals-layer-api-production-v1/versions/9efc2daf-927c-4236-8c4b-94837efef50d" --- # Fundamentals Layer API OpenAPI specification document. ```json {"openapi":"3.0.1","info":{"title":"Fundamentals Layer API","description":"Company fundamentals for Saudi and GCC listed companies: reported financial statements and history, financial ratios, key highlights, analyst estimates and opinions, and market-level financial results.","contact":{"name":"Argaam IT","url":"https://www.argaam.com","email":"developer@argaam.com"},"version":"v1.1"},"paths":{"/api/v1.1/companies/{stockSymbol}/financials":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values. Defaults to `3`."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get the latest financial statements for a company","description":"Returns the most recent reported income statement, balance sheet and cash-flow line items for the company. Use `fiscalPeriod` and `year` to pin a specific reporting period.","operationId":"getCompaniesByStockSymbolFinancials"}},"/api/v1.1/companies/{stockSymbol}/financials/history":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"year","in":"query","schema":{"type":"integer","format":"int32"},"example":2023,"description":"Calendar year to filter by, e.g. `2025`."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values. Defaults to `3`."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."},{"name":"fiscalPeriod","in":"query","schema":{"type":"string","default":""},"example":"year","description":"Fiscal period within the year: `1`-`4` for quarters, `5` for the full year."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get historical financial statements for a company","description":"Returns the reported financial statement history for the company across fiscal periods. Use `fromYear`/`toYear` or `numberOfYear` to bound the range.","operationId":"getCompaniesByStockSymbolFinancialsHistory"}},"/api/v1.1/companies/{stockSymbol}/financials/reports":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values. Defaults to `3`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get reports for a company","description":"Returns the reports for the company identified by `stockSymbol`.","operationId":"getCompaniesByStockSymbolFinancialsReports"}},"/api/v1.1/companies/{stockSymbol}/ratios":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get financial ratios for a company","description":"Returns the financial ratios for the company identified by `stockSymbol`.","operationId":"getCompaniesByStockSymbolRatios"}},"/api/v1.1/companies/{stockSymbol}/ratios/history":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"year","in":"query","schema":{"type":"integer","format":"int32"},"example":2023,"description":"Calendar year to filter by, e.g. `2025`."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."},{"name":"fiscalPeriod","in":"query","schema":{"type":"string","default":""},"example":"year","description":"Fiscal period within the year: `1`-`4` for quarters, `5` for the full year."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get historical series for a company","description":"Returns the historical series for the company identified by `stockSymbol`.","operationId":"getCompaniesByStockSymbolRatiosHistory"}},"/api/v1.1/companies/{stockSymbol}/highlights":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get key financial highlights for a company","description":"Returns the key financial highlights for the company identified by `stockSymbol`.","operationId":"getCompaniesByStockSymbolHighlights"}},"/api/v1.1/companies/{stockSymbol}/analyst-estimates":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get analyst estimates for a company","description":"Returns the analyst estimates for the company identified by `stockSymbol`.","operationId":"getCompaniesByStockSymbolAnalystEstimates"}},"/api/v1.1/companies/by-symbol/{symbol}/analyst-estimates":{"get":{"tags":["Companies"],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Company trading symbol / ticker (e.g. `2222` for Saudi Aramco)."},{"name":"fiscalYear","in":"query","description":"Fiscal year to query (e.g. `2024`).","schema":{"type":"integer","format":"int32"},"example":2024},{"name":"period","in":"query","description":"Fiscal period type: `year` (default), `quarter`, or `interim`. Defaults to `year`.","schema":{"type":"string","default":"year"},"example":"year"},{"name":"fsFieldId","in":"query","description":"Financial statement field ID to query. Default `54` (Net Income). Defaults to `54`.","schema":{"type":"integer","format":"int32","default":54},"example":54}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get analyst estimates vs. actuals for a company identified by trading symbol.","description":"Returns analyst estimates for the specified financial statement field\r\n(`fsFieldId`) compared against actual published values for the same\r\nperiod. Useful for building earnings-surprise charts and consensus\r\nbeat/miss dashboards.\r\n \r\n**Common `fsFieldId` values**\r\n| ID | Field |\r\n|---|---|\r\n| `54` (default) | Net Income |\r\n| `1` | Revenue |\r\n| `3` | Operating Income |\r\n| `8` | EPS |\r\n \r\n**Period values** — `year` (default), `quarter`, `interim`.\r\n \r\n**Tip:** For ID-based estimates use\r\n`GET /companies/{id}/analyst-estimates`.","operationId":"getCompaniesBySymbolBySymbolAnalystEstimates"}},"/api/v1.1/markets/{marketId}/analyst-estimates":{"get":{"tags":["Markets"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Market ID (e.g. `1` for Saudi Tadawul).","example":3},{"name":"year","in":"query","description":"Fiscal year (e.g. `2024`).","schema":{"type":"integer","format":"int32"},"example":2023},{"name":"period","in":"query","description":"Fiscal period type: `year` (default), `quarter`, or `interim`. Defaults to `year`.","schema":{"type":"string","default":"year"},"example":"year"},{"name":"fiscalPeriod","in":"query","description":"Specific sub-period: `year`, `q1`–`q4`, `i1`–`i3`. Defaults to the period type's natural value.","schema":{"type":"string","default":""},"example":"year"},{"name":"fsFieldId","in":"query","description":"Financial statement field ID. Default `54` (Net Income). Defaults to `54`.","schema":{"type":"integer","format":"int32","default":54},"example":54}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get analyst estimates aggregated across all companies in a market.","description":"Returns consensus analyst estimates for a specific financial statement\r\nfield across all coverage companies in the market for the given fiscal\r\nyear and period.\r\n \r\n**Common `fsFieldId` values**\r\n| ID | Field |\r\n|---|---|\r\n| `54` (default) | Net Income |\r\n| `1` | Revenue |\r\n| `3` | Operating Income |\r\n| `8` | EPS |\r\n \r\n**Period values** — `year` (default), `quarter`, `interim`.\r\n \r\n**Tip:** For a single company's estimates use\r\n`GET /companies/{companyId}/analyst-estimates`.","operationId":"getMarketsByMarketIdAnalystEstimates"}},"/api/v1.1/markets/{marketId}/financial-results":{"get":{"tags":["Markets"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Market ID (e.g. `1` for Saudi Tadawul).","example":3},{"name":"year","in":"query","description":"Fiscal year (e.g. `2023`).","schema":{"type":"integer","format":"int32"},"example":2023},{"name":"period","in":"query","description":"Fiscal period type: `year` (default), `quarter`, or `interim`. Defaults to `year`.","schema":{"type":"string","default":"year"},"example":"year"},{"name":"fiscalPeriod","in":"query","description":"Specific sub-period: `year`, `q1`–`q4`, `i1`–`i3`.","schema":{"type":"string","default":""},"example":"year"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get aggregated financial results for all companies in a market.","description":"Returns the published financial statement results for all companies\r\nin the specified market for the given fiscal year and period.\r\n \r\nUseful for building a market-wide results summary table or for\r\ncomparing company-level performance within the same period.\r\n \r\n**Period values** — `year` (default), `quarter`, `interim`.\r\n \r\n**Tip:** To drill into a single company's results within this market use\r\n`GET /markets/{marketId}/financial-results/{companyId}`.","operationId":"getMarketsByMarketIdFinancialResults"}},"/api/v1.1/companies/{stockSymbol}/analyst-opinions":{"get":{"tags":["Companies"],"parameters":[{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"example":"2222","description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values. Defaults to `3`."},{"name":"page","in":"query","schema":{"type":"integer","format":"int32","default":1},"example":1,"description":"1-based page number. Defaults to `1`."},{"name":"records","in":"query","schema":{"type":"integer","format":"int32","default":10},"example":10,"description":"Maximum number of records to return. Defaults to `10`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get analyst opinions for a company","description":"Returns the analyst opinions for the company identified by `stockSymbol`.\n\nPaginated: use `page` and `pageSize`.","operationId":"getCompaniesByStockSymbolAnalystOpinions"}},"/api/v1.1/markets/{marketId}/analyst-opinions":{"get":{"tags":["Markets"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Market ID (e.g. `1` for Saudi Tadawul).","example":3},{"name":"page","in":"query","description":"Page number (1-based). Default: `1`. Defaults to `1`.","schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"records","in":"query","description":"Records per page. Default: `10`. Defaults to `10`.","schema":{"type":"integer","format":"int32","default":10},"example":10}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get analyst buy/sell/hold opinions across companies in a market.","description":"Returns paginated analyst opinion records for all covered companies\r\nin the specified market. Each record includes the analyst firm name,\r\nrating (Buy / Overweight / Hold / Underweight / Sell), target price,\r\nand publication date.\r\n \r\n**Pagination** is controlled by `?page=` (1-based) and `?records=`.\r\nDefault: page 1, 10 records per page.\r\n \r\n**Tip:** For estimates (EPS, revenue consensus) use\r\n`GET /markets/{marketId}/analyst-estimates`. For a single company's\r\nopinions use `GET /companies/{companyId}/analyst-opinions`.","operationId":"getMarketsByMarketIdAnalystOpinions"}},"/api/v1.1/companies/market-ratios/{marketId}":{"get":{"tags":["Companies"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values.","example":3},{"name":"fiscalPeriodTypeId","in":"query","schema":{"type":"integer","format":"int32","default":1},"example":1,"description":"Numeric fiscal period type identifier (quarterly / half-yearly / annual). Defaults to `1`."},{"name":"excludeAramco","in":"query","schema":{"type":"integer","format":"int32","default":0},"example":0,"description":"When `true`, excludes Saudi Aramco (2222) from aggregates so a single mega-cap does not dominate market-level figures. Defaults to `0`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response2"}}}}},"summary":"Get a market-level ratio by market symbol","description":"Returns the market-level ratio identified by `marketSymbol`.","operationId":"getCompaniesMarketRatiosByMarketId"}},"/api/v1.1/companies/rankings/{marketId}/{metric}":{"get":{"tags":["Companies"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values.","example":3},{"name":"metric","in":"path","required":true,"schema":{"type":"string"},"description":"Ranking metric to sort by (e.g. `pe`, `market-cap`, `dividend-yield`)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get the company ranking for a metric","description":"Returns companies in the market ranked highest-first by the requested metric.","operationId":"getCompaniesRankingsByMarketIdByMetric"}},"/api/v1.1/companies/rankings/{marketId}/lowest-20/{metric}":{"get":{"tags":["Companies"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values.","example":3},{"name":"metric","in":"path","required":true,"schema":{"type":"string"},"description":"Ranking metric to sort by (e.g. `pe`, `market-cap`, `dividend-yield`)."},{"name":"period","in":"query","schema":{"type":"string","default":"quarter"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `quarter`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get the bottom 20 companies by metric","description":"Returns the twenty lowest-ranked companies in the market for the requested metric.","operationId":"getCompaniesRankingsByMarketIdLowest20ByMetric"}},"/api/v1.1/markets/{marketId}/financial-results/{stockSymbol}":{"get":{"tags":["Markets"],"parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"integer","format":"int32"},"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values.","example":3},{"name":"stockSymbol","in":"path","required":true,"schema":{"type":"string"},"description":"Tadawul stock symbol of the company, e.g. `2222` (Saudi Aramco)."},{"name":"year","in":"query","schema":{"type":"integer","format":"int32"},"example":2023,"description":"Calendar year to filter by, e.g. `2025`."},{"name":"period","in":"query","schema":{"type":"string","default":"year"},"example":"year","description":"Time window for the series, e.g. `1d`, `1m`, `3m`, `1y`, `5y`. Defaults to `year`."},{"name":"fiscalPeriod","in":"query","schema":{"type":"string","default":""},"example":"year","description":"Fiscal period within the year: `1`-`4` for quarters, `5` for the full year."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1Response"}}}}},"summary":"Get financial results for a specific company within a market.","description":"Returns the published financial statement results for a single company\r\nwithin the market context, for the specified fiscal year and period.\r\n \r\nThis is a scoped version of `GET /markets/{marketId}/financial-results`\r\nthat narrows to one company without needing to filter client-side.\r\n \r\n**Period values** — `year` (default), `quarter`, `interim`.\r\n \r\n**Tip:** For the structured financial statement (income statement,\r\nbalance sheet) for a company use\r\n`GET /companies/{companyId}/financials/history?year={year}`.","operationId":"getMarketsByMarketIdFinancialResultsByStockSymbol"}}},"components":{"schemas":{"ApiV1Meta":{"type":"object","properties":{"page":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"totalRecords":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32","readOnly":true},"hasNextPage":{"type":"boolean","readOnly":true},"hasPreviousPage":{"type":"boolean","readOnly":true}},"additionalProperties":false},"ApiV1RateLimit":{"type":"object","properties":{"limit":{"type":"integer","format":"int32"},"remaining":{"type":"integer","format":"int32"},"reset":{"type":"string","format":"date-time"}},"additionalProperties":false},"ApiV1Response":{"type":"object","properties":{"success":{"type":"boolean"},"apiVersion":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"},"requestId":{"type":"string","nullable":true},"data":{"nullable":true},"meta":{"$ref":"#/components/schemas/ApiV1Meta"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit"}},"additionalProperties":false},"ApiV1Response2":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true for successful responses."},"apiVersion":{"type":"string","description":"Semantic API version (e.g., \"1.0.0\").","nullable":true},"timestamp":{"type":"string","description":"UTC timestamp when the response was generated.","format":"date-time"},"requestId":{"type":"string","description":"Unique request identifier for tracing.","nullable":true},"data":{"description":"The response payload.","nullable":true},"meta":{"$ref":"#/components/schemas/ApiV1Meta2"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit2"}},"additionalProperties":false,"description":"Standardized successful API response wrapper for v1.0.0 endpoints."},"ApiV1RateLimit2":{"type":"object","properties":{"limit":{"type":"integer","description":"Total request quota for the current window.","format":"int32"},"remaining":{"type":"integer","description":"Remaining requests in the current window.","format":"int32"},"reset":{"type":"string","description":"UTC timestamp when the rate limit window resets.","format":"date-time"}},"additionalProperties":false,"description":"Rate limit information returned with each response."},"ApiV1Meta2":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-based).","format":"int32"},"pageSize":{"type":"integer","description":"Number of items per page.","format":"int32"},"totalRecords":{"type":"integer","description":"Total number of records available across all pages.","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages.","format":"int32","readOnly":true},"hasNextPage":{"type":"boolean","description":"Whether there is a next page available.","readOnly":true},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page available.","readOnly":true}},"additionalProperties":false,"description":"Pagination and metadata information for collection responses."}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey"},"ApiKeyAuthQuery":{"type":"apiKey","in":"query","name":"apikey"}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"url":"https://api.argaam.com","description":"Argaam API Gateway (Production)"}]} ```