Fraud API

Score any ONCE account for fraud and abuse risk with a single request. Powered by ONCE Fraud Detection, the API returns a weighted risk score and a breakdown of the signals behind it — so you can act on risk inside your own systems.

Scores and flags only

The Fraud API returns only risk scores and flags. It never exposes IP addresses, personal data, account details, or any internal detection method. That makes every response safe to store, log, and use directly in your own systems.

Free for a limited time

The Fraud API is free while it is in public beta. This free period is temporary and will end — usage-based pricing will apply once the beta wraps up. Build now to take advantage of it, and we will share pricing and notice well before anything changes.

Authentication

The Fraud API uses your ONCE user account plus an API key — there is no separate signup. Create a key (a Personal Access Token) in the ONCE dev center:

1Open Settings → Developer in the ONCE dev center.
2Create an API key with the once:fraud scope enabled.
3Send the key as a bearer token on every request using the Authorization header.

Authorization header

Authorization: Bearer once_pat_xxx

Keep your key secret. A key without the once:fraud scope will be rejected with a 403.

Endpoint

POSThttps://once.app/v1/fraud/score

Send a JSON body with the email address of the ONCE account you want to score:

Request body

{
  "email": "artist@example.com"
}

A complete request with curl:

curl

curl -X POST https://once.app/v1/fraud/score \
  -H "Authorization: Bearer once_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"artist@example.com"}'

Response

A 200 returns the overall score, severity, and the full set of flags that were evaluated:

200 · application/json

{
  "email": "artist@example.com",
  "score": 145,
  "maxScore": 300,
  "severity": "high",
  "computedAt": "2026-07-05T07:30:00Z",
  "flags": [
    {
      "code": "banned_account_metadata_match",
      "label": "Release metadata matches a banned account",
      "category": "account_integrity",
      "severity": "high",
      "triggered": true,
      "points": 60
    },
    {
      "code": "audio_match_multiple",
      "label": "Audio fingerprint matches on multiple tracks",
      "category": "rights",
      "severity": "high",
      "triggered": false,
      "points": 0
    }
  ]
}

Field	Type	Description
email	string	The email address that was scored, echoed back on the response.
score	integer	Overall weighted risk score, from 0 up to maxScore.
maxScore	integer	Maximum possible score. Currently 300.
severity	string	Overall severity: none, low, medium, high, or critical.
computedAt	string \| null	ISO 8601 timestamp of the most recent scoring, or null if the account has never been scored.
flags	array	List of flag objects (see below). Empty for cleared, no-risk accounts.

Severitynonelowmediumhighcritical

Cleared, no-risk accounts return a zero score, a severity of none, and an empty flag list:

Cleared account

{
  "score": 0,
  "severity": "none",
  "flags": []
}

Flags

Every flag belongs to one of seven categories. A flag fires only when its signal is present; untriggered flags are still returned so you can see the full picture.

Category	What it covers
rights	Copyright, licensing, and audio-fingerprint conflicts on the release.
account_integrity	Signals that the account or its metadata matches known bad or banned accounts.
content	Problems with the release content itself: metadata, artwork, or audio authenticity.
distribution	Anomalies in how a release is distributed across stores and territories.
streaming	Suspicious streaming activity, such as artificial or manipulated plays.
behavior	Account behavior that deviates from legitimate artist activity.
abuse	Platform abuse, spam, and policy-evasion signals.

Each flag object carries the following fields:

Field	Type	Description
code	string	Stable identifier for the flag.
label	string	Human-readable description of what the flag detects.
category	string	One of the seven flag categories listed below.
severity	string	Flag severity: low, medium, high, or critical.
triggered	boolean	Whether this flag fired for the scored account.
points	integer	Points this flag contributes to the score. 0 when not triggered.

Rate limits

requests / minute

1,000

requests / day

These are the free-tier limits, applied per account. Exceeding either one returns a 429. Need more headroom? Reach out and we can tune your limits.

Errors

403

Forbidden

The API key is missing the once:fraud scope. Enable it in the ONCE dev center and try again.

404

Not Found

No ONCE account exists for the supplied email address.

429

Too Many Requests

You have exceeded the rate limit or your daily quota. Retry after the window resets.

Start scoring in minutes

Create a key with the once:fraud scope and send your first request. Free while we are in public beta.

Create an API key Fraud Detection overview