Announcements API - Documentation

Getting Started

This API provides secure access to announcements data from the Muscat Securities Market and Official Gazettes. All endpoints require API key authentication.

Authentication

Include your API key in every request using the X-API-Key header:

X-API-Key: your-api-key-here

Rate Limiting: Each API key is limited to 1,000 requests per hour. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per hour
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: When the rate limit resets (ISO 8601 timestamp)

Response Structure

All successful API responses follow a consistent structure:

Top-Level Response Object

Field	Type	Description
`success`	boolean	Indicates if the request was successful (`true` for success, `false` for errors)
`results`	array	Array of announcement objects (present on success)
`count`	integer	Number of announcements returned in this response
`limit`	integer	The limit value used for this request (for /recent endpoint)
`companyCr`	string	The company CR queried (for /by-cr endpoint)
`error`	string	Error message (only present when `success` is `false`)

Response Headers

In addition to the JSON body, each response includes important HTTP headers:

X-RateLimit-Limit: 1000 - Your hourly request limit
X-RateLimit-Remaining: 987 - Requests remaining in current hour
X-RateLimit-Reset: 2025-12-10T19:30:00.000Z - When your limit resets

Endpoints

GET /announcements/recent

Retrieve the most recent announcements ordered by publication sequence.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of announcements to return. Default: 500, Min: 1, Max: 10,000

Example Request

curl -H "X-API-Key: your-api-key" \
  "https://api.yourdomain.com/announcements/recent?limit=100"

Example Response

{
  "success": true,
  "results": [
    {
      "id": "doc-id",
      "companyCr": "1234567",
      "englishName": "EXAMPLE COMPANY LLC",
      "arabicName": "شركة مثال ش.م.م",
      "publicationDate": "2025-12-10T00:00:00.000Z",
      "type": "disclosure",
      "announcementText": "...",
      "sequence": 12345
    }
  ],
  "count": 100,
  "limit": 100
}

GET /announcements/by-cr

Retrieve all announcements for a specific company by their CR (Commercial Registration) number.

Query Parameters

Parameter	Type	Required	Description
`companyCr`	string	Required	The company's Commercial Registration number

Example Request

curl -H "X-API-Key: your-api-key" \
  "https://api.yourdomain.com/announcements/by-cr?companyCr=1234567"

Example Response

{
  "success": true,
  "results": [
    {
      "id": "doc-id",
      "companyCr": "1234567",
      "englishName": "EXAMPLE COMPANY LLC",
      "arabicName": "شركة مثال ش.م.م",
      "publicationDate": "2025-12-10T00:00:00.000Z",
      "type": "disclosure",
      "announcementText": "...",
      "sequence": 12345
    }
  ],
  "count": 15,
  "companyCr": "1234567"
}

Announcement Object Fields

Each announcement object in the results array contains the following fields. Fields marked with Required are always present, while Optional fields may be missing for some announcements.

Field	Type	Status	Description
`id`	string	Required	Description: Unique Firestore document identifier for this announcement. Example: "0IOXRXCNJHfSihANNic8" Use case: Use this ID to reference specific announcements, avoid duplicates, or build direct links to announcement details.
`companyCr`	string	Required	Description: Commercial Registration (CR) number issued by the Ministry of Commerce. This is the primary company identifier in Oman. Example: "1186752" Use case: Use to link announcements across time, query all announcements for a specific company, or validate company identity. Essential for tracking company history and regulatory compliance.
`englishName`	string	Required	Description: Official company name in English, typically in all uppercase. Example: "OMAN CABLES INDUSTRY" Use case: Display company name in English interfaces, search by company name, or generate English reports.
`arabicName`	string	Required	Description: Official company name in Arabic script. Example: "شركة صناعة الكابلات العمانية" Use case: Display company name in Arabic interfaces, support bilingual applications, or match against official Arabic documents.
`title`	string	Required	Description: The announcement headline or subject line, typically describes what the announcement is about. Example: "MSX Disclosure: Announcement of the Ordinary General Meeting resolutions" Use case: Display as the announcement headline, use for search/filtering, or generate notifications with meaningful context.
`type`	string	Required	Description: Category of the announcement. Common values include "Disclosure", "Liquidation", or "Gazette". Example: "Disclosure" Use case: Filter announcements by type, categorize in UI, apply type-specific business logic, or generate type-specific reports.
`publication`	string	Required	Description: Source publication where the announcement was originally published. Example: "MSX Website" Use case: Track data sources, display source attribution, or filter by publication source. Common sources include "MSX Website" and "Official Gazette".
`publicationDate`	string	Required	Description: Date and time when the announcement was published, in ISO 8601 format with UTC timezone. Example: "2025-12-10T16:29:13.000Z" Format: ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) Use case: Sort announcements chronologically, filter by date range, display publication dates to users, or trigger time-based workflows. Always in UTC timezone.
`fileUrl`	string	Required	Description: Direct HTTPS URL to the processed PDF file hosted on data.qanoon.om. Example: "https://data.qanoon.om/risk/OCAI-10122025-13.pdf" Use case: Provide download links, embed PDFs in viewers, or archive announcement documents. These files are permanently hosted and accessible.
`originalPdfUrl`	string	Optional	Description: Original PDF URL from the source website (e.g., MSX website). May become unavailable over time. Example: "https://www.msx.om//msmdocs/images/newsdocs/OCAI-10122025-13.pdf" Use case: Reference to original source, verify data integrity, or access source website. For permanent access, use `fileUrl` instead.
`sequence`	integer	Required	Description: Sequential ordering number where higher values indicate more recent announcements. Guarantees consistent ordering. Example: 13449 Use case: Reliable sorting (use instead of dates for ordering), track new announcements (query where sequence > last_seen), or detect gaps in data.
`stockCode`	string	Optional	Description: Muscat Securities Market (MSX) stock ticker symbol for listed companies. Example: "OCAI" Use case: Link to stock market data, filter disclosures for specific stocks, or integrate with trading systems. Only present for MSX-listed companies.
`createdAt`	string	Required	Description: Timestamp when this announcement record was created in the database, in ISO 8601 format. Example: "2025-12-10T12:31:13.233Z" Use case: Track when data was ingested, audit data freshness, or implement incremental data syncing.
`updatedAt`	string	Required	Description: Timestamp of the last update to this announcement record, in ISO 8601 format. Example: "2025-12-10T12:31:13.233Z" Use case: Detect modified records, implement change detection, or maintain data synchronization.

Complete Response Examples

These are real examples from the live API showing actual announcement data:

Example 1: Get Recent Announcements (Success)

Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.decree.om/announcements/recent?limit=2"

Response:

{
  "success": true,
  "results": [
    {
      "id": "0IOXRXCNJHfSihANNic8",
      "arabicName": "شركة صناعة الكابلات العمانية",
      "englishName": "OMAN CABLES INDUSTRY",
      "companyCr": "1186752",
      "title": "MSX Disclosure: Announcement of the Ordinary General Meeting resolutions",
      "type": "Disclosure",
      "publication": "MSX Website",
      "publicationDate": "2025-12-10T16:29:13.000Z",
      "fileUrl": "https://data.qanoon.om/risk/OCAI-10122025-13.pdf",
      "sequence": 13449,
      "originalPdfUrl": "https://www.msx.om//msmdocs/images/newsdocs/OCAI-10122025-13.pdf",
      "stockCode": "OCAI",
      "createdAt": "2025-12-10T12:31:13.233Z",
      "updatedAt": "2025-12-10T12:31:13.233Z"
    },
    {
      "id": "X967s4nVSdNdq5NodSSM",
      "arabicName": "بنك نزوى",
      "englishName": "BANK NIZWA",
      "companyCr": "1152878",
      "title": "MSX Disclosure: Appointment of Deputy Chief Executive Officer and Chief Operations Officer at Bank Nizwa S.A.O.G",
      "type": "Disclosure",
      "publication": "MSX Website",
      "publicationDate": "2025-12-10T15:31:50.000Z",
      "fileUrl": "https://data.qanoon.om/risk/BKNZ-10122025-11.pdf",
      "sequence": 13448,
      "originalPdfUrl": "https://www.msx.om//msmdocs/images/newsdocs/BKNZ-10122025-11.pdf",
      "stockCode": "BKNZ",
      "createdAt": "2025-12-10T11:46:21.098Z",
      "updatedAt": "2025-12-10T11:46:21.098Z"
    }
  ],
  "count": 2,
  "limit": 2
}

Example 2: Get Announcements by Company CR

Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.decree.om/announcements/by-cr?companyCr=1186752"

Expected Response Structure:

{
  "success": true,
  "results": [
    {
      "id": "...",
      "companyCr": "1186752",
      "englishName": "OMAN CABLES INDUSTRY",
      ...
    }
  ],
  "count": 23,
  "companyCr": "1186752"
}

Note: The /by-cr endpoint returns all announcements for the specified company, sorted by sequence (most recent first). The number of results varies by company.

Field Value Types

Understanding the different types of values you'll encounter in key fields:

Announcement Types

The type field can contain the following values:

"Disclosure" - MSX company disclosures (financial reports, board meetings, material events)
"Liquidation" - Company liquidation and dissolution notices
"Gazette" - Official Gazette announcements (government notices, legal publications)

Publication Sources

The publication field indicates where the announcement was published:

"MSX Website" - Muscat Securities Market official disclosures
"Official Gazette" - Government of Oman official gazette publications

Date Formats

All dates use ISO 8601 format with UTC timezone:

Format: YYYY-MM-DDTHH:mm:ss.sssZ
Example: "2025-12-10T16:29:13.000Z"
Timezone: Always UTC (indicated by the Z suffix)
Parsing: Compatible with JavaScript Date(), Python datetime.fromisoformat(), and most modern date libraries

Data Interpretation Guide

Practical tips for working with the announcements data:

Ordering and Chronology

Always use sequence for ordering: The sequence field provides reliable ordering (higher = more recent). While publicationDate represents when the announcement was published, use sequence for sorting to ensure consistency.
Tracking new announcements: Store the highest sequence number you've seen, then query for announcements with sequence > last_seen_sequence
Historical vs recent: Higher sequence numbers indicate more recent announcements. Sequence numbers are assigned chronologically as announcements are ingested.

Company Identification

Use companyCr as the primary key: The CR number is the official company identifier and remains constant even if the company name changes
Linking announcements: Query by companyCr to get complete company history across all announcement types
Name variations: Company names may appear differently across announcements due to translations or official name changes, but the CR number stays consistent

PDF Document Access

Use fileUrl for reliable access: These files are permanently hosted and won't expire
Original sources: The originalPdfUrl links to the source website but may become unavailable over time
Direct downloads: All PDF URLs support direct download without authentication

Handling Missing Fields

stockCode: Only present for MSX-listed companies. Will be absent for unlisted companies or gazette announcements
originalPdfUrl: May be missing for older announcements or certain data sources
Always check for field existence before accessing optional fields in your code

Date and Time Handling

All timestamps are UTC: Convert to local time in your application as needed
publicationDate: When the announcement was officially published
createdAt: When our system first ingested this announcement (may be later than publication)
updatedAt: When the record was last modified (usually same as createdAt unless corrected)

Working with Multiple Languages

Bilingual support: Both englishName and arabicName are always present for every announcement
Search considerations: When implementing search, consider searching both English and Arabic names
Display: Display both names for maximum clarity, or choose based on user's language preference

Error Responses

401 Unauthorized

Missing or invalid API key

{
  "success": false,
  "error": "Invalid or missing API key. Please provide a valid API key in the X-API-Key header."
}

429 Too Many Requests

Rate limit exceeded

{
  "success": false,
  "error": "Rate limit exceeded",
  "limit": 1000,
  "resetAt": "2025-12-10T15:30:00.000Z"
}

400 Bad Request

Missing required parameters

{
  "success": false,
  "error": "companyCr parameter is required"
}

500 Internal Server Error

Server error

{
  "success": false,
  "error": "Error message"
}

Best Practices

Cache responses when appropriate to reduce API calls
Monitor rate limit headers to avoid hitting limits
Use reasonable limit values - only request what you need
Handle errors gracefully with proper retry logic
Keep your API key secure - never expose it in client-side code
Use HTTPS for all API requests