Hinweishelden IBAN API

API for detecting fraudulent IBANs and fake shops.

Questions about the API, or need a trial access? Write to us at peterson@hinweishelden.com. Use of the API is governed by the API Agreement.

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.iban.hinweishelden.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.iban.hinweishelden.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
vop_result	string	Filter by Verification of Payee result: not_checked, match, close_match, no_match, not_possible
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",
      "vop_result": "no_match",
      "vop_checked_at": "2026-02-27 10:05:19",
      "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

Usage and Credits

Every request to the IBAN and entity endpoints is logged. Accounts are billed in one of two modes:

Mode	Behaviour
flat	Unlimited requests within the rate limit.
credits	Each request to /v1/ibans/, /v1/ibans/search/, /v1/entities/ or /v1/entities/search/ costs 1 credit per delivered record, at least 1 credit per request. A search with one hit costs 1, a list page with 200 records costs 200. Status endpoints are free. Requests that fail (4xx/5xx) are not charged.

Credits accounts receive the header X-Credits-Remaining on every data response and can read their balance from GET /v1/status/auth/. The page size of a credits account is capped at its remaining balance: with 10 credits left, limit=500 returns 10 records and has_more: true. When the balance reaches zero, requests return 402 with error code credits_exhausted until new credits are added.

Verification of Payee

Every IBAN carries vop_result, the outcome of a Verification of Payee check of the reported recipient name against the account holder at the bank, and vop_checked_at, when that check was made. Values: not_checked (default), match, close_match, no_match, not_possible (the bank does not answer VoP requests). A no_match on a fraud report means the fraudsters use a name that differs from the account holder, which is itself a strong signal.

Access Period and Delayed Data

Two optional restrictions can apply to an account. Both are visible in GET /v1/status/auth/.

Field	Behaviour
access_expires_at	Trial or time-limited accounts stop working at this moment. Every request afterwards returns 403 with error code access_expired. null means unlimited.
data_delay_days	Delayed accounts only receive records that are at least this many days old (based on timestamp_created). 0 means no delay.
bank_scope	Scoped accounts only receive IBANs whose BIC starts with one of the listed prefixes (e.g. BBVA, BBVADEFF) or whose German bank code matches a listed 8-digit code, plus entities linked to at least one such IBAN. An empty list means all banks.

Polling with a delay: for delayed accounts the parameters created_after, changed_after and cursor are interpreted in visibility time (real time plus the delay), and next_cursor is returned in the same way. A client that polls with created_after set to its last poll time therefore receives every record on the day it becomes visible, with no gaps. Individual records may be delivered more than once; treat the record id as the key.

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
402	credits_exhausted	Credit balance is zero (credits accounts only)
403	access_expired	The account's access period has ended
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.4.0 — Full API Reference