API Reference

Base URL: https://api.txnworks.com/v1

All requests require Authorization: Bearer txnw_sk_... header. All request and response bodies are JSON.

POST /v1/score

Score a transaction against 140+ behavioral signals. Returns a risk score, label, and contributing signals in under 50ms.

Request body parameters

Parameter	Type	Required	Description
transaction_id	string	Yes	Your unique identifier for this transaction. Used for feedback correlation and score retrieval.
amount	number	Yes	Transaction amount as a decimal. E.g., 215.00
currency	string	Yes	ISO 4217 currency code. E.g., "USD"
merchant_id	string	Yes	Your identifier for the merchant or checkout session.
card_fingerprint	string	Yes	Stable identifier for the payment card, not the full PAN.
device_id	string	Yes	Stable identifier for the device. Use your device fingerprinting solution or the Txnworks device SDK.
ip_address	string	Yes	IPv4 or IPv6 address of the client at time of transaction.
user_agent	string	No	Browser User-Agent string. Extends device fingerprint signals.
session_id	string	No	Your session identifier. Used for session-level behavioral signals.
email	string	No	Customer email address. Used for identity consistency signals. Not stored after scoring.
billing_address	object	No	{ street, city, state, zip, country }. Used for address consistency signals.
shipping_address	object	No	{ street, city, state, zip, country }. Used for shipping/billing divergence signal.

Response

{
  "transaction_id": "txn_1750000001",
  "score": 742,
  "label": "BLOCK",
  "confidence": 0.91,
  "latency_ms": 44,
  "contributing_signals": [
    { "signal": "geo_velocity", "weight": 0.38, "value": "high" },
    { "signal": "device_fingerprint", "weight": 0.29, "value": "new_device" },
    { "signal": "txn_count_1h", "weight": 0.21, "value": 8 },
    { "signal": "ip_reputation", "weight": 0.12, "value": "flagged" }
  ],
  "thresholds_applied": { "block": 700, "review": 400 }
}

POST /v1/feedback

Submit an outcome label for a previously scored transaction. Used to retrain signal weights. Available on Growth and Scale plans.

Parameter	Type	Required	Description
transaction_id	string	Yes	The transaction_id from the original /v1/score call.
outcome	string	Yes	One of: "confirmed_fraud", "false_positive", "confirmed_legitimate"
notes	string	No	Optional free-text context for your internal records. Not used in model training.

Response

{ "status": "accepted", "transaction_id": "txn_1750000001" }

GET /v1/cases

List recent transactions flagged for REVIEW or BLOCK. Useful for building a manual review queue UI.

Query parameters

Parameter	Type	Default	Description
label	string	all	Filter by label: "REVIEW", "BLOCK", or omit for all
limit	integer	50	Number of cases to return. Max 200.
cursor	string	—	Pagination cursor from previous response next_cursor field.
since	string	—	ISO 8601 datetime. Return cases scored after this timestamp.

Response

{
  "cases": [
    { "transaction_id": "txn_abc", "score": 742, "label": "BLOCK", "scored_at": "2026-06-01T14:22:11Z" },
    { "transaction_id": "txn_def", "score": 521, "label": "REVIEW", "scored_at": "2026-06-01T14:22:09Z" }
  ],
  "next_cursor": "cur_xyz",
  "has_more": true
}

GET /v1/score/{id}

Retrieve the full score record for a previously scored transaction by transaction_id.

No request body. Returns the same format as POST /v1/score, with the addition of scored_at timestamp and feedback field showing any submitted outcome labels.

Response

{
  "transaction_id": "txn_1750000001",
  "score": 312,
  "label": "ALLOW",
  "confidence": 0.87,
  "latency_ms": 41,
  "scored_at": "2026-06-01T14:22:11Z",
  "contributing_signals": [...],
  "feedback": null
}

Returns 404 if the transaction_id is not found, or if the score record is outside your plan's retention window.

Error codes

HTTP Status	Error code	Description
400	invalid_request	Missing required field or invalid field value.
401	unauthorized	API key missing or invalid.
403	forbidden	API key lacks permission for this endpoint (e.g. score-only key calling /v1/feedback).
404	not_found	Transaction ID not found or outside retention window.
429	rate_limited	Exceeded plan rate limit. See Retry-After header.
500	internal_error	Transient server error. Retry with exponential backoff.