canonical: https://jentic.com/apis/ipsnare.com/ipsnare # IPSnare API The IPSnare API ingests click tracking records for job listings, one click per request. Each record ties a publisher_id, click_id, and job_id to the visitor's user_ip, user agent, the job and click countries, and a creation timestamp. Records also carry bot detection fields, a bot_score from 0 to 100 and an is_bot flag with an optional bot_type, plus expiry flags and a free-form metadata object for campaign or source details. ## For AI agents Send job-ad click events to IPSnare with publisher, job, IP, country, and bot-score fields so each click is recorded for tracking and bot analysis. ## Scope Does not query stored clicks, generate reports, or score bots itself. Use for ingesting job-ad click records only. ## Capabilities - Record a job-listing click with its publisher_id, click_id, job_id, and visitor user_ip - Attach bot detection results to a click with bot_score, is_bot, and an optional bot_type - Store the job_country and click_country as ISO 3166-1 alpha-2 codes for geographic click analysis - Carry campaign or traffic-source details on a click through the free-form metadata object - Mark a click as expired with the expired flag and expired_at timestamp ## Use cases ### Agent-forwarded click events An AI agent processing a batch of job-ad redirects needs to record each click without hand-building requests. Through Jentic the agent searches for 'record a job ad click', loads the IPSnare ingest operation with its input schema, and sends one ClickData record per click with the X-API-Key header attached at call time. The 201 response returns the click_id and timestamp so the agent can confirm each write. Example prompt: Call POST /clicks with publisher_id pub_456, user_ip 192.0.2.10, click_id click_789abc, job_id job_def123, job_country US, click_country US, created_at 2026-11-05T12:30:45Z, bot_score 15, and is_bot 0, then confirm the returned click_id ### Bot-scored job ad traffic A job board paying publishers per click wants every click stored with its bot assessment so invalid traffic can be reviewed later. Each IPSnare click record holds a bot_score from 0 to 100 and an is_bot flag, with bot_type naming the kind of bot when one is detected. Example prompt: Call POST /clicks for a click with bot_score 92, is_bot 1, and bot_type crawler, including all required publisher, job, country, and timestamp fields ### Campaign attribution on clicks A recruitment marketer running campaigns across sources tags every click with where it came from. The metadata object accepts arbitrary keys such as campaign_id and source, and publisher_click_id keeps the publisher's own identifier beside IPSnare's click_id for later reconciliation. Example prompt: Call POST /clicks with publisher_click_id pub_click_xyz and metadata containing campaign_id camp_001 and source google, plus all required fields ## Key resources - **Clicks** — Ingest one click record with publisher, job, IP, country, bot detection, expiry, and metadata fields ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 70 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 100 / 100 - Developer Experience & Jentic Compatibility: 90 / 100 - AI-Readiness & Agent Experience: 58 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 50 / 100 - **View full report:** https://jentic.com/apis/ipsnare.com/ipsnare/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring IPSnare by hand means sending the X-API-Key header and building a ClickData body with nine required fields and strict country and timestamp formats. Through Jentic you install once, import IPSnare from the API Directory, store the key once, and your agent calls it with the input schema in hand. - **Permission scoping:** IPSnare exposes one operation, POST /clicks, so a rule decides whether your agent may write click records at all. The target publisher and job travel in the request body, so rules bound the operation the agent may call, not which publisher it writes for. - **Credential handling:** Your IPSnare API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'record a job ad click', and Jentic returns the IPSnare ingest operation with its ClickData input schema so the agent sends every required field. ## Related APIs - **Plausible Analytics** — Privacy-focused web analytics with an events API, rather than job-ad click records - **Fingerprint** — Device identification and bot detection to produce the signals stored on each click - **IP2Proxy** — Proxy and VPN detection for the user_ip behind a click ## FAQ ### What authentication does the IPSnare API use? Per its OpenAPI spec, the IPSnare API authenticates with an API key sent in the X-API-Key request header on POST /clicks. Through Jentic the key is stored by your own instance and attached at call time, so the agent never sees it. ### Which fields are required to ingest a click with the IPSnare API? The ClickData schema requires publisher_id, user_ip, click_id, job_id, job_country, click_country, created_at, bot_score, and is_bot. Countries are two-letter ISO 3166-1 alpha-2 codes, created_at is an ISO 8601 timestamp, and optional fields include user_agent, publisher_click_id, expired, expired_at, bot_type, and metadata. A missing field returns a 400 validation error. ### Is there an IPSnare MCP server? You don't need an MCP server to give your agent IPSnare. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the click ingest operation without loading another server's tool definitions into its context. ### Can I limit what my agent is allowed to do with the IPSnare API? Yes. The spec has a single write, POST /clicks, so a rule that allows it lets the agent record clicks and nothing else, and leaving it out keeps the agent from writing click data at all. Every call it makes is logged. ### How do I record a click through Jentic? Search Jentic for 'record a job ad click', load the POST /clicks operation, and execute it with the required ClickData fields. A 201 response returns success, the click_id, and a timestamp. To run it on your own infrastructure, install Jentic One from its GitHub repo.