12321 API12321.cn ↗
Access official notices, anti-fraud warnings, complaint statistics, and phone/SMS complaint lookup from China's 12321 Network Spam Reporting Center via a structured API.
What is the 12321 API?
The 12321.cn API provides structured access to 11 endpoints covering China's official telecom spam and anti-fraud reporting center, including paginated notices, warning articles, downloadable reports, and live complaint statistics. The search_phone_complaint and search_sms_complaint endpoints let you query complaint handling records for specific phone numbers after solving a captcha via get_captcha. All content originates from 12321.cn, operated under MIIT oversight.
curl -X GET 'https://api.parse.bot/scraper/70ef7607-617c-4881-8567-a5dfb4c86ab4/get_notices?page=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace 12321-cn-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.twelve321_cn_anti_spam_reporting_center_api import AntiSpam, NoticeNotFound
client = AntiSpam()
# Get today's dashboard statistics
dashboard = client.dashboards.get()
print(dashboard.today_complaint_count)
# Browse the latest warnings from the dashboard
for warning in dashboard.latest_warnings:
print(warning.title, warning.type, warning.time)
# List warning articles with auto-pagination
for summary in client.warnings.list(limit=5):
print(summary.id, summary.title)
# Drill into a specific warning for full content
detail = summary.details()
print(detail.title, detail.source, detail.update_time)
print(detail.content)
# Fetch a notice by ID
notice = client.notices.get(id="33")
print(notice.title, notice.publish_date)
print(notice.content)
# List news articles
for article in client.articles.list(limit=3):
print(article.id, article.title, article.url)
# List reports
for report in client.reports.list(limit=5):
print(report.title, report.date, report.download_url)
Retrieve the list of official announcements/notices. Returns paginated results with notice titles, dates, and IDs. The site has approximately 2 pages of notices total.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
{
"type": "object",
"fields": {
"page": "string, current page number",
"items": "array of notice objects with id, title, date, and url"
},
"sample": {
"data": {
"page": "1",
"items": [
{
"id": "33",
"url": "https://12321.cn/notice_detail?aid=33.html",
"date": "2016-10-20",
"title": "《电子邮件服务指南》公开征求意见"
}
]
},
"status": "success"
}
}About the 12321 API
Notices, Warnings, and News
The get_notices and get_warnings endpoints return paginated lists of official announcements and anti-fraud alerts respectively, each item carrying an id, title, date or url. The site currently has approximately 2 pages of notices. Pass those IDs to get_notice_detail or get_warning_detail for the full text — detail endpoints include content, publish_date or update_time, and a source attribution field on warnings. The get_news endpoint follows the same paginated structure for general news articles.
Reports and Homepage Statistics
get_reports returns the full catalogue of downloadable report documents with title, date, and a download_url for each file — no pagination parameters are required. get_homepage_stats returns two things at once: today_complaint_count (a string reflecting the day's total intake) and latest_warnings, an array of recent warning entries each carrying index, id, title, type, time, and url. This endpoint is useful for dashboards that need a live daily pulse from the center.
Captcha-Gated Complaint Search
Searching complaint records for a specific number requires a two-step flow. First call get_captcha, which returns image_base64 — a base64-encoded PNG you decode and solve. Pass the solved code along with the target phone, session_id, and encryption_key to either search_phone_complaint (voice call complaints) or search_sms_complaint (text message complaints). Both return a records array where each entry contains time, type, and status. If the captcha code is wrong or stale, the API returns a stale_input error.
Complaint Agreement Text
get_complaint_notice_sms returns the full content of the pre-complaint agreement users must acknowledge before submitting an SMS complaint. This is useful for applications that replicate or explain the complaint filing process to end users.
The 12321 API is a managed, monitored endpoint for 12321.cn — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 12321.cn changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official 12321.cn API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor today's telecom complaint volume using
today_complaint_countfromget_homepage_statsfor a real-time fraud activity dashboard. - Look up the complaint handling status of a suspected spam phone number using
search_phone_complaint. - Archive and parse official 12321 notices by fetching paginated results from
get_noticesand retrieving full text viaget_notice_detail. - Aggregate downloadable annual or quarterly fraud reports from
get_reportsfor compliance or research purposes. - Build a Chinese-language anti-fraud news feed using warning article titles and full content from
get_warningsandget_warning_detail. - Surface the latest warning highlights on a security portal using the
latest_warningsarray fromget_homepage_stats. - Verify SMS complaint records for a phone number by chaining
get_captchawithsearch_sms_complaint.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does 12321.cn provide an official public developer API?+
What does `search_phone_complaint` actually return, and how is it different from `search_sms_complaint`?+
search_phone_complaint returns complaint records for voice call complaints filed against a phone number, while search_sms_complaint returns records for SMS-related complaints against the same number. Both return a records array with time, type, and status per entry, plus a message describing the overall result. The distinction maps directly to the two separate complaint categories on the 12321 platform.Does the captcha flow expire between calls?+
get_captcha is tied to a session and becomes stale if too much time passes or if an incorrect code is submitted — the search endpoints return a stale_input error in that case. You need to call get_captcha again to get a fresh image and solve it before retrying.Can I retrieve the full text of a news article through the `get_news` endpoint?+
get_news returns only the paginated list of articles with id, title, and url — there is no get_news_detail endpoint analogous to the notice and warning detail endpoints. Full article content is not currently exposed. You can fork this API on Parse and revise it to add a news detail endpoint.Does the API expose historical complaint statistics beyond today's count?+
get_homepage_stats returns only today_complaint_count and the latest warning entries displayed on the homepage. Historical complaint trend data is not exposed. You can fork this API on Parse and revise it to add a historical statistics endpoint if that data becomes available on the site.