{"service": "marketdata read API", "auth": "X-API-Key header, or ?api_key= for a quick curl", "notes": ["Jalali dates are strings, YYYY/MM/DD, and sort correctly as strings.", "to_date = null means the person is still in office.", "A person is anchored on their national id, never on their name: ~2 % of mentions carry an empty name and ~0.5 % an over-read one.", "Each scope supersedes only itself — an auditors' meeting does not end a board term."], "endpoints": [{"path": "/v1/health", "auth": false}, {"path": "/v1/companies/search", "params": ["q (>=2 chars)", "limit (<=200)", "offset"], "note": "substring match on the normalised name, ranked"}, {"path": "/v1/companies/{national_id}"}, {"path": "/v1/companies/{national_id}/officers", "params": ["as_of=1404/01/20", "scope=board|auditor|liquidation"]}, {"path": "/v1/people/{person_nid}", "params": ["limit", "offset"]}], "roles": {"chair": "رئیس هیئت مدیره", "vice_chair": "نایب رئیس هیئت مدیره", "ceo": "مدیرعامل", "board_member": "عضو هیئت مدیره", "board_alt": "عضو علی‌البدل هیئت مدیره", "secretary": "منشی هیئت مدیره", "treasurer": "خزانه‌دار", "deputy": "قائم مقام", "supervisor": "ناظر", "auditor": "بازرس اصلی", "auditor_alt": "بازرس علی‌البدل", "liquidator": "مدیر تصفیه"}, "scopes": {"board": "هیئت مدیره", "auditor": "بازرسان", "liquidation": "تصفیه"}}