E12 DEVELOPERS
Short Links & Company Facts API
供 IGEARS One、WeBetter 及內部職員使用。請向 E12 管理員申請獨立 client key。此頁不會顯示任何金鑰。
Authentication
Private endpoints require Authorization: Bearer YOUR_CLIENT_KEY. Each client can make 600 requests per UTC hour. Keys only access that client's own links. HTTPS is required. Public listing reads allow 60 requests per minute per IP. Rate limits return 429 and Retry-After.
Create a link
POST /api/v1/links
Content-Type: application/json
{"target_url":"https://webetter.co/zh-HK/geo-audit?url=artascent-design.com&ref=cmp33","title":"AI 可讀性審核","campaign_tag":"competitor-33","customer_ref":"opaque-customer-id","append_params":{"utm_source":"igears"}}
201 {"code":"Ab3De7F","short_url":"https://e12.hk/s/Ab3De7F","preview_url":"https://e12.hk/s/Ab3De7F+"}
Optional: listing_id, ISO-8601 expires_at, and staff-only slug. The tuple (client, target_url, campaign_tag, customer_ref) is idempotent: retries return the original code and configuration, including its active state. Use a new campaign tag for a new link. Destinations are restricted to configured iGears sites and published, claimed company website domains. Recursive short links are refused.
| Endpoint | Response |
|---|---|
GET /api/v1/links/{code} | Link details and totals: clicks, human_clicks, unique_humans, first/last click, countries and devices. |
GET /api/v1/links?campaign_tag=… | Up to 100 links; continue with next_after_id as after_id. |
GET /api/v1/links/{code}/clicks?since=… | Up to 500 raw click rows; classification and UTM snapshot included. Continue with after_id. |
POST /api/v1/links/{code}/deactivate | Disable the link. Expired/disabled links return 410. |
GET /s/{code}+ | Public destination preview; not counted as a redirect click. |
Redirects and measurement
Redirects use HTTP 302 and Cache-Control: no-store. Destination query parameters take priority, followed by append_params, followed by incoming utm_* and ref parameters. Fragments are preserved. Referrers are stored without query strings. Browser/scanner signatures and configured IP ranges classify human, bot and proxy traffic; classification is an estimate, not proof of a person. Bare curl or “Mozilla” requests count as bots.
Raw clicks and daily hashed IP identifiers expire after 180 days. Aggregate counts and country/device totals are kept. unique_humans is the sum of daily unique IP hashes per link: the same visitor on two days can count twice. Countries can be Unknown when trusted geolocation is unavailable. All response timestamps are UTC. The optional first-human webhook uses a durable retry queue, sends code/customer_ref/campaign_tag/ts, and signs the exact JSON body with HMAC-SHA256 in X-E12-Signature. Consumers should deduplicate by code and validate the signature. Polling is also supported.
Prospect pages
POST /api/v1/listings/prospect
{"name_zh":"公司中文名稱","name_en":"Company name","website":"https://company.example","industry":"construction","district":"九龍灣","phone":"+852 1234 5678","source_urls":["https://company.example/contact"],"evidence_note":"Company name, district and public business phone verified on the official site."}IGEARS One only. Use verified public business facts. No personal names, private contact details, vendor claims or contract claims. Optional public_email must be a published company address on its own domain. Existing companies are reused; suppressed listings cannot be recreated. Response: listing_id, slug, url, state and ai_discovery_opt_in (false for new prospects). Claiming follows the existing owner-verification process.
GET /api/v1/listings/{slug} is a public, rate-limited JSON-LD endpoint returning the same Organization, WebPage and FAQ facts shown on the page. Public citation is independent of E12 AI Business Match and partner-feed opt-in.