Hinweishelden IBAN API

API for detecting fraudulent IBANs and fake shops.

Quick Start

The Hinweishelden IBAN API provides access to fraud intelligence data including reported IBANs and associated entities (fake shops, fraudulent offers, etc.). All responses are JSON.

1. Get your API key

Your API key will be provided by the Hinweishelden team. Keep it secure — it cannot be recovered if lost.

2. Test your key

curl -H "X-API-Key: YOUR_API_KEY" https://api.example.com/v1/status/auth/

Expected response:

{
  "authenticated": true,
  "user_email": "partner@bank.de",
  "user_status": "general_user"
}

3. Fetch recent IBANs

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.example.com/v1/ibans/?created_after=2026-02-01T00:00:00Z&include_entities=true"

Authentication

All API requests require an API key sent via the X-API-Key header:

X-API-Key: hwh_your_api_key_here

Invalid or missing keys return 401 Unauthorized.

User Tiers

Tier	Access
Basic	IBANs only (without recipient_name, proof_url, or entities). Entity endpoints return 403.
General	Full read access to all endpoints.
Staff	Full read/write access including staff endpoints.

Endpoints

All endpoints are prefixed with /v1/.

IBANs

List Filters

Parameter	Type	Description
changed_after	ISO 8601	IBANs changed after this timestamp
created_after	ISO 8601	IBANs created after this timestamp
report_type	string	fraud or release
include_entities	boolean	Include linked entity data in response

Search Parameters

Parameter	Type	Description
id	integer	Exact ID match
iban	string	Exact IBAN match
bic	string	Exact BIC match
recipient_name	string	Contains match (case-insensitive)

Example Response

GET /v1/ibans/?changed_after=2026-02-27T00:00:00Z&include_entities=true

{
  "results": [
    {
      "id": 42,
      "recipient_name": "FERREIRA",
      "iban": "FR7614518292670016542294013",
      "bic": "FTNOFRP1XXX",
      "date_of_report": "2026-02-12 00:00:00",
      "timestamp_created": "2026-02-12 06:23:21",
      "timestamp_changed": "2026-02-27 10:05:19",
      "report_type": "fraud",
      "confidence": "black",
      "proof_url": "https://s3.hetzner.com/...?X-Amz-Expires=604800&...",
      "comment": null,
      "entities": [
        {
          "id": 7,
          "type": "shop",
          "medium": "website",
          "report_type": "fraud",
          "url": "https://okatode.com",
          "source_category": "reported_internally",
          "sources": [
            "https://www.auktionshilfe.info/thread/35603",
            "https://seitcheck.de/okatode-com/"
          ],
          "comment": "Fake shop selling firewood and pellets. Stolen company data in imprint, no delivery, prepayment only.",
          "shop_screenshot_url": "https://s3.hetzner.com/...?X-Amz-Expires=604800&...",
          "timestamp_created": "2026-02-12 06:23:21",
          "timestamp_changed": "2026-02-27 10:05:19"
        }
      ]
    }
  ],
  "next_cursor": "2026-02-27T10:05:19.210000Z",
  "has_more": true
}

Entities

All entities are returned. Screenshots are provided as pre-signed S3 URLs valid for 7 days.

List Filters

Parameter	Type	Description
changed_after	ISO 8601	Entities changed after this timestamp
created_after	ISO 8601	Entities created after this timestamp
type	string	Filter by entity type (e.g. shop)
medium	string	Filter by medium (e.g. website, letter, sms)
report_type	string	fraud or release
source_category	string	Filter by source category
iban	string	Only entities linked to this exact IBAN

Search Parameters

Parameter	Type	Description
id	integer	Exact ID match
url	string	Contains match (case-insensitive)

Example Response

GET /v1/entities/?created_after=2026-02-01T00:00:00Z

{
  "results": [
    {
      "id": 7,
      "type": "shop",
      "medium": "website",
      "report_type": "fraud",
      "url": "https://okatode.com",
      "source_category": "reported_internally",
      "sources": [
        "https://www.auktionshilfe.info/thread/35603",
        "https://seitcheck.de/okatode-com/"
      ],
      "comment": "Fake shop selling firewood and pellets. Stolen company data in imprint, no delivery, prepayment only.",
      "shop_screenshot_url": "https://s3.hetzner.com/...?X-Amz-Expires=604800&...",
      "timestamp_created": "2026-02-12 06:23:21",
      "timestamp_changed": "2026-02-27 10:05:19"
    }
  ],
  "next_cursor": "2026-02-12T06:23:21.000000Z",
  "next_cursor_id": 7,
  "has_more": false
}

Status

Pagination

List endpoints use cursor-based pagination. The cursor is an ISO 8601 timestamp.

Parameter	Default	Description
cursor	—	Timestamp cursor from previous response's next_cursor
cursor_id	—	ID cursor from previous response's next_cursor_id
limit	100	Page size (max 500)

When has_more is true, use both next_cursor and next_cursor_id from the response in your next request to fetch the next page.

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid IBAN format.",
    "details": {}
  }
}

HTTP Status	Code	Description
400	validation_error	Invalid request data
401	authentication_failed	Invalid or missing API key
403	permission_denied	Insufficient permissions
404	not_found	Resource not found
429	rate_limited	Too many requests

Pre-signed URLs

Screenshot fields (proof_url, shop_screenshot_url) return pre-signed S3 URLs. These URLs are valid for 7 days from the time of the API response. Fetch new URLs by re-requesting the resource after expiry.

---

Hinweishelden IBAN API v1.0.0 — Full API Reference