Integration Guide

Integrating IP Snare into your job board or aggregator is simple and takes less than 15 minutes.

1. Get Your API Key

Sign up for an account and navigate to the "Settings" page to generate your unique API key.

2. Make an api request to:

curl -X POST https://api.ipsnare.com/v1/track
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
  "source_id": "pub_456",
  "user_ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "source_click_id": "click_789abc",
  "job_id": "job_def123",
  "job_country": "US",
  "user_country": "US",
  "publisher_source_click_id": "pub_click_xyz",
  "created_at": "2025-11-10T12:30:45Z",
  "expired": 0,
  "expired_at": null,
  "bot_score": 0.15,
  "is_bot": 0,
  "bot_type": "",
  "final": true,
  "destination_id": "dest_id_example",
  "metadata": {"campaign_id": "camp_001", "source": "google"}
}'

Responses:

Valid Response

Response Code: 200

{
  "success": true
}

Missing Parameters

Response Code: 422

{
  "success": false,
  "errors": [
    {
      "field": "source_id",
      "message": "Missing required parameter"
    }
  ]
}

Invalid Parameters

For example, sending country codes that are not ISO 3166-1 alpha-2 codes will result in an invalid parameters response.

Response Code: 422

{
  "success": false,
  "errors": [
    {
      "field": "job_country",
      "message": "Invalid country code"
    },
    {
      "field": "user_country",
      "message": "Invalid country code"
    }
  ]
}

Invalid API Key

Response Code: 401

{
  "success": false,
  "errors": [
    {
      "field": "api_key",
      "message": "Invalid API key"
    }
  ]
}

Server Error

Response Code: 500

{
  "success": false,
  "errors": [
    {
      "field": "",
      "message": "Internal server error"
    }
  ]
}