Developer Documentation

Giveaway API

REST API for programmatic Instagram giveaway draws. Only the verification endpoint (GET /api/verify/<hash>) is public today; the draw endpoints and webhooks below are not self-serve, and API access is by request.

REST + JSONWebhooksSHA-256 verifiedIdempotent

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are issued per account when API access is granted.

curl https://api.pickawin.app/v1/draws \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Quick start: run a draw

Submit an Instagram URL plus the number of winners. The API returns winners, the SHA-256 verification hash, and a downloadable certificate URL.

curl -X POST https://api.pickawin.app/v1/draws \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draw_2026_04_28_001" \
  -d '{
    "url": "https://www.instagram.com/p/CxxxxxxxxxX/",
    "winners": 3,
    "extras": 2,
    "filters": {
      "require_tag": true,
      "min_tag_count": 1,
      "exclude_duplicates": true
    },
    "tier": "premium",
    "webhook_url": "https://yourapp.com/webhooks/pickawin"
  }'

Response (200 OK):

{
  "id": "drw_01HXYZABC",
  "status": "completed",
  "url": "https://www.instagram.com/p/CxxxxxxxxxX/",
  "comments_processed": 8243,
  "winners": [
    { "username": "@maria_silva", "comment": "Love this! @ana_costa", "drawn_at": "2026-04-28T14:23:11Z" },
    { "username": "@joao_p", "comment": "yes please @luis123", "drawn_at": "2026-04-28T14:23:11Z" },
    { "username": "@carla.dev", "comment": "@bia_xyz this is for us", "drawn_at": "2026-04-28T14:23:11Z" }
  ],
  "extras": [
    { "username": "@bruno_45", "comment": "@matt_y" },
    { "username": "@helena", "comment": "@ana" }
  ],
  "verification": {
    "sha256": "8a3f...c91e",
    "verify_url": "https://pickawin.app/verify/8a3f...c91e",
    "certificate_pdf": "https://pickawin.app/cert/drw_01HXYZABC.pdf"
  },
  "duration_ms": 28412
}

Endpoints

POST

/v1/draws

Run a new draw. Idempotency-Key header recommended.

GET

/v1/draws/:id

Retrieve a draw by ID.

GET

/v1/draws

List draws with pagination (?cursor, ?limit).

POST

/v1/comments/scrape

Scrape comments only (no draw). Useful for previews.

GET

/api/verify/:hash

Public — check whether a SHA-256 hash matches a published result (automatic draws with a public result page).

POST

/v1/webhooks

Webhooks

Webhooks fire when a draw completes or fails. Signed with HMAC-SHA256 in the X-PickAWin-Signature header.

POST https://yourapp.com/webhooks/pickawin
X-PickAWin-Signature: sha256=4f8b...a91e
Content-Type: application/json

{
  "event": "draw.completed",
  "draw_id": "drw_01HXYZABC",
  "url": "https://www.instagram.com/p/CxxxxxxxxxX/",
  "winners": [...],
  "verification": { "sha256": "8a3f...c91e" },
  "timestamp": "2026-04-28T14:23:11Z"
}

Rate limits

Rate limits are set per account when access is granted.

Pricing

Pricing for API access is agreed on request. Draws on the site are a one-time payment per draw (Standard from US$ 7.99, Premium from US$ 14.99; price shown in your currency before paying).

Get an API key

API access is by request. To run a draw now, use the site.

Run a draw now →