The Custom Fraud Rules API lets you programmatically list, create, update, and delete the custom fraud rules configured for your organization in Singular's Fraud Prevention product.

The authenticated user must have access to the Fraud Rules feature in the Singular platform.

Access to this feature can be set up as View Only or View and Edit, under that user's role permissions in Team Management (the Custom Rules permission, under Fraud).

Endpoints

The following API endpoints are available:

Get Fraud Rule Metadata	GET	https://api.singular.net/api/v1/fraud/rules/meta	Use to get option values for dimensions whose values should be selected from known metadata (apps, sources, countries, regions, cities, install source bundles).
List Fraud Rules	GET	https://api.singular.net/api/v1/fraud/rules	Returns all custom fraud rules configured for your organization.
Create or Update a Fraud Rule	POST	https://api.singular.net/api/v1/fraud/rules	Creates a rule when id is absent from the request body, or updates a rule when id is present.
Delete a Fraud Rule	DELETE	https://api.singular.net/api/v1/fraud/rules	Permanently deletes an existing rule by id.

Authentication

All Singular API calls require your Singular API key. To retrieve your key, log into the Singular platform and go to Developer Tools > Reporting API Keys.

Put the API key in the authorization HTTP header (see the code examples), or pass it as the api_key query parameter. Do not prefix the header value with Bearer.

Missing or invalid API keys return HTTP 401 with the following response body:

{
  "status": 1,
  "substatus": 1,
  "value": "Missing API Key"
}

Rate Limits

The fraud rule endpoints are limited to 10 requests per minute per organization. This limit is shared across list, metadata, create, update, and delete requests.

{
  "status": 1,
  "substatus": 1,
  "value": "Too many requests. Maximum allowed are 10 requests in a minute"
}

Response Envelopes

Case	HTTP status	Body
GET success	200	A raw JSON array of rule objects.
GET metadata success	200	A raw JSON object with external-safe option lists.
POST / DELETE success	200	`{"status": 0, "substatus": 0, "value": ...}`
Validation or expected application error	200	`{"status": 1, "substatus": 1, "value": "<error message>"}`
Insufficient permissions (View Only user calling POST/DELETE)	403	`{"status": 1, "substatus": 1, "value": "User doesn't have permissions for this operation"}`
Authentication failure	401	`{"status": 1, "substatus": 1, "value": "<error message>"}`
Rate limit exceeded	429	`{"status": 1, "substatus": 1, "value": "Too many requests. Maximum allowed are 10 requests in a minute"}`

Rule Object

Each fraud rule returned by the API has the following fields:

Field	Type	Description
id	string	External fraud rule ID. This is a string value returned by GET and must be sent unchanged for update and delete requests.
name	string	Rule name.
active	boolean	Whether the rule is enabled.
action	string	One of Suspicious, Reject, Whitelist.
created	number	Seconds since Unix epoch.
updated	number	Seconds since Unix epoch.
conditions	array	Array of condition objects.

Condition Object

Field	Type	Required	Description
dimension	string	Yes	Dimension name (see Supported Dimensions).
operator	string	Most dimensions	Allowed values depend on the dimension. blacklisted_ip does not support an operator.
values	varies	Most dimensions	Shape depends on the dimension and operator. Some dimensions do not support values.
custom_field_name	string	custom_parameter only	Custom parameter field name. Allowed characters are letters, numbers, underscore, and hyphen.

Supported Dimensions

Dimension	Operators	values type
source	in, not_in	Non-empty array of source value names from the metadata endpoint.
app	in, not_in	Non-empty array of app bundle id/platform values from metadata, e.g. `com.example.app/Android`.
publisher	in, not_in	Non-empty array of strings.
click_country	in, not_in	Non-empty array of strings.
install_country	in, not_in	Non-empty array of strings.
install_region	in, not_in	Non-empty array of strings.
install_city	in, not_in	Non-empty array of strings.
campaign_name	in, not_in	Non-empty array of strings.
installer_source	in, not_in	Non-empty array of strings.
time_to_install	lt, gt	Single numeric value.
dupes	lt, gt	Single numeric value.
click_distance	lt, gt	Single numeric value.
click_speed	lt, gt	Single numeric value.
click_to_click_time	lt, gt	Single numeric value.
os_version	lt, gt	Single scalar value.
app_version	lt, gt	Single scalar value.
sdk_version	lt, gt	Single scalar value.
custom_parameter	lt, gt, in, not_in	Requires custom_field_name (letters, numbers, underscores, or hyphens). lt/gt require one numeric value; in/not_in require a non-empty array of strings or numbers.
attribution_method	fingerprinting, strong_id	No values field.
integration_type	s2s, sdk	No values field.
receipt_validation	not_valid, valid	No values field.
os_type	Android, iOS	No values field.
touchpoint_type	click, impression	No values field.
referral_click_injection	No operator	No values field.
organic_poaching	No operator	No values field.
android_install_validation	not_valid, valid	No values field.
blacklisted_ip	No operator	No values field.

Get Fraud Rule Metadata Endpoint

GET

https://api.singular.net/api/v1/fraud/rules/meta

Usage

Use this endpoint to get optional values that you can use when building rule conditions. Values for apps and sources are external-safe: app values are the app bundle id plus platform, and source values are display names. The API translates these values back to internal IDs when rules are created or updated, so you should use the values returned here as-is in your Create or Update a Fraud Rule requests.

Sample Query

import requests

url = "https://api.singular.net/api/v1/fraud/rules/meta"
api_key = <...>  # Retrieve API Key from Singular platform at Developer Tools > Reporting API Keys

response = requests.get(url, headers={'Authorization': api_key})
print(response.json())

curl --location --request GET 'https://api.singular.net/api/v1/fraud/rules/meta' \
--header 'authorization: <API KEY>'

Sample Output

{
  "apps": [
    {"value": "com.example.app/Android", "label": "Example App Android"},
    {"value": "com.example.app/iOS", "label": "Example App iOS"}
  ],
  "sources": [
    {"value": "Example Network", "label": "Example Network"}
  ],
  "countries": [
    {"value": "US", "label": "United States"}
  ],
  "regions": [],
  "cities": [],
  "install_source_bundles": []
}

Output Parameters

Field	Type	Description
apps	array	App options. value is `<app bundle id>/<platform>`; label is the app name plus platform.
sources	array	Source options. value and label are the source display name.
countries	array	Country options for click_country and install_country.
regions	array	Region options for install_region.
cities	array	City options for install_city.
install_source_bundles	array	Install source options for installer_source.

List Fraud Rules Endpoint

GET

https://api.singular.net/api/v1/fraud/rules

Usage

Use this endpoint to retrieve all custom fraud rules configured for your organization, including each rule's ID, active status, action, and conditions. App and source condition values are externalized the same way as the Get Fraud Rule Metadata endpoint.

Sample Query

import requests

url = "https://api.singular.net/api/v1/fraud/rules"
api_key = <...>  # Retrieve API Key from Singular platform at Developer Tools > Reporting API Keys

response = requests.get(url, headers={'Authorization': api_key})
print(response.json())

curl --location --request GET 'https://api.singular.net/api/v1/fraud/rules' \
--header 'authorization: <API KEY>'

Sample Output

[
  {
    "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12",
    "name": "High click speed",
    "active": true,
    "action": "Reject",
    "created": 1783231200.0,
    "updated": 1783231800.0,
    "conditions": [
      {"dimension": "click_speed", "operator": "gt", "values": 10},
      {"dimension": "app", "operator": "in", "values": ["com.example.app/Android"]},
      {"dimension": "source", "operator": "not_in", "values": ["Example Network"]}
    ]
  }
]

Output Parameters

An array of Rule Objects (see above), each including its Condition Objects.

Create or Update a Fraud Rule Endpoint

POST

https://api.singular.net/api/v1/fraud/rules

Usage

Use this endpoint to create a new custom fraud rule, or to update an existing one.

If id is absent from the request body, the API creates a new rule.
If id is present, the API verifies that the rule exists for your organization and updates it. When updating, send the full desired conditions array — it replaces the rule's existing conditions rather than merging with them.

Body Parameters

Field	Type	Required	Default	Description
id	string	No		Existing rule ID returned by List Fraud Rules. Present means update; absent means create.
name	string	Yes		Rule name, maximum 64 characters.
active	boolean	No	true	Whether the rule is enabled. Use false to create or update a paused rule.
action	string	Yes		One of Suspicious, Reject, Whitelist.
conditions	array	Yes		Array of condition objects.

Sample Query (Create a Rule)

import requests
import json

url = "https://api.singular.net/api/v1/fraud/rules"
api_key = <...>  # Retrieve API Key from Singular platform at Developer Tools > Reporting API Keys

payload = json.dumps({
  "name": "Suspicious custom parameter",
  "active": True,
  "action": "Suspicious",
  "conditions": [
    {
      "dimension": "custom_parameter",
      "custom_field_name": "risk_score",
      "operator": "gt",
      "values": 80
    }
  ]
})

response = requests.post(url, data=payload, headers={'Authorization': api_key, 'Content-Type': 'application/json'})
print(response.json())

curl --location --request POST 'https://api.singular.net/api/v1/fraud/rules' \
--header 'authorization: <API KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Suspicious custom parameter",
  "active": true,
  "action": "Suspicious",
  "conditions": [
    {
      "dimension": "custom_parameter",
      "custom_field_name": "risk_score",
      "operator": "gt",
      "values": 80
    }
  ]
}'

Sample Query (Update a Rule)

This example updates an existing rule returned by List Fraud Rules. Keep the rule id unchanged, and send the full desired conditions array.

import requests
import json

url = "https://api.singular.net/api/v1/fraud/rules"
api_key = <...>  # Retrieve API Key from Singular platform at Developer Tools > Reporting API Keys

payload = json.dumps({
  "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12",
  "name": "Paused source rejection rule",
  "active": False,
  "action": "Reject",
  "conditions": [
    {"dimension": "source", "operator": "in", "values": ["Example Network"]}
  ]
})

response = requests.post(url, data=payload, headers={'Authorization': api_key, 'Content-Type': 'application/json'})
print(response.json())

curl --location --request POST 'https://api.singular.net/api/v1/fraud/rules' \
--header 'authorization: <API KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12",
  "name": "Paused source rejection rule",
  "active": false,
  "action": "Reject",
  "conditions": [
    {"dimension": "source", "operator": "in", "values": ["Example Network"]}
  ]
}'

Tip: Pausing a rule this way (active: false) keeps its name and conditions intact so it can be re-enabled later. This is the recommended alternative to deleting a rule — see the Delete a Fraud Rule section below.

Sample Output

{
  "status": 0,
  "substatus": 0,
  "value": {
    "rule": {
      "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12",
      "name": "Paused source rejection rule",
      "active": false,
      "action": "Reject",
      "created": 1783231200.0,
      "updated": 1783231800.0,
      "conditions": [
        {"dimension": "source", "operator": "in", "values": ["Example Network"]}
      ]
    },
    "created": false
  }
}

Validation Messages

Scenario	Message
Invalid id (update)	Field `id` must be a valid fraud rule id
Update targets missing rule	Fraud rule does not exist
Missing name	Missing required field `name`
Long name	Field `name` must be 64 characters or fewer
Invalid active	Field `active` must be a boolean
Invalid action	Field `action` must be one of: Suspicious, Reject, Whitelist
Invalid conditions	Field `conditions` must be an array
Unsupported dimension	Condition N has unsupported dimension `<dimension>`
Unsupported operator	Condition N with dimension `<dimension>` supports operators: <operators>
Operator not allowed	Condition N with dimension `<dimension>` does not support `operator`
Missing custom field	Condition N with dimension `custom_parameter` requires `custom_field_name`
Invalid custom field	Condition N with dimension `custom_parameter` requires `custom_field_name` to contain only letters, numbers, underscores, or hyphens
Invalid source values	Condition N with dimension `source` requires string or integer `values`
Unknown app	Condition N with dimension `app` has unknown app `<value>`
Invalid list values	Condition N with dimension `<dimension>` requires string `values`
Values not allowed	Condition N with dimension `<dimension>` does not support `values`
Invalid single value	Condition N with operator `<operator>` requires a single value
Invalid numeric value	Condition N with dimension `<dimension>` requires a numeric `values` field
Invalid version value	Condition N with dimension `<dimension>` requires a valid version `values` field

Delete a Fraud Rule Endpoint

DELETE

https://api.singular.net/api/v1/fraud/rules

Deletion is irreversible. Once a rule is deleted through this endpoint, it cannot be recovered or restored — you would need to recreate it from scratch, and it will be assigned a new rule id.

We strongly recommend against automating deletion. If your goal is to temporarily or permanently stop a rule from taking action, use the Create or Update a Fraud Rule endpoint to set active to false instead. This keeps the rule's name and conditions in place so it stays visible in your rule list and can be re-enabled at any time. Reserve the DELETE endpoint for manual, deliberate cleanup of rules you are certain you no longer need.

Usage

Use this endpoint to permanently delete an existing rule. The id must be an ID string returned by List Fraud Rules.

Body Parameters

Field	Type	Required	Description
id	string	Yes	Rule ID returned by List Fraud Rules.

Sample Query

import requests
import json

url = "https://api.singular.net/api/v1/fraud/rules"
api_key = <...>  # Retrieve API Key from Singular platform at Developer Tools > Reporting API Keys

payload = json.dumps({
  "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12"
})

response = requests.delete(url, data=payload, headers={'Authorization': api_key, 'Content-Type': 'application/json'})
print(response.json())

curl --location --request DELETE 'https://api.singular.net/api/v1/fraud/rules' \
--header 'authorization: <API KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "fr_Y2J2M0F1cA_V2b9e9bbac4d8f12"
}'

Sample Output

{
  "status": 0,
  "substatus": 0,
  "value": "Deleted Successfully"
}

Validation Messages

Scenario	Message
Missing id	Missing required field `id`
Invalid id	Field `id` must be a valid fraud rule id
Rule does not exist	Fraud rule does not exist

Custom Fraud Rules API Reference

Endpoints

Authentication

Rate Limits

Response Envelopes

Rule Object

Condition Object

Supported Dimensions

Get Fraud Rule Metadata Endpoint

Usage

Sample Query

Sample Output

Output Parameters

List Fraud Rules Endpoint

Usage

Sample Query

Sample Output

Output Parameters

Create or Update a Fraud Rule Endpoint

Usage

Body Parameters

Sample Query (Create a Rule)

Sample Query (Update a Rule)

Sample Output

Validation Messages

Delete a Fraud Rule Endpoint

Usage

Body Parameters

Sample Query

Sample Output

Validation Messages