Ban Callbacks

Ban callbacks notify publishers whenever a user's status changes for a specific demand type. This allows publishers to synchronize their systems with BitLabs and react appropriately when a user is banned, placed under review, or reinstated.

Overview

Ban callbacks are triggered only when a user's status changes. They can be used to:

Restrict access to specific demand types when users are banned.
Temporarily hold payouts while a user is under review.
Resume normal operation once a user has been cleared and reinstated.
Keep publisher systems synchronized with the user's current status in BitLabs.

Note: Ban statuses are applied per demand type. A user may be affected for surveys without being affected for offers, and vice versa.

Callback Parameters

The following macros are available when configuring a ban callback URL:

Macro	Description
`[%BAN:TYPE%]`	The demand type affected by the status change. Possible values: `surveys`, `offers`.
`[%BAN:REASON%]`	A plain-text explanation for the status change. Intended primarily for internal logging and support purposes.
`[%BAN:UNTIL%]`	The timestamp until which the current status applies. Uses the ISO 8601 format in UTC. This value may be empty.
`[%BAN:STATUS%]`	The user's current status for the specified demand type. Possible values: `active`, `banned`, `shadow_ban`, `review`, `on_hold`.

Status Values

`active`

The user is in good standing and may participate normally in the specified demand type.

This status is also sent when a previously banned or reviewed user has been reinstated.

Recommended action: Allow the user to access the specified demand type and resume normal payout processing.

`banned`

The user is prohibited from accessing the demand type specified in [%BAN:TYPE%].

Recommended action: Prevent the user from accessing the affected demand type.

`shadow_ban`

The user is prohibited from accessing the specified demand type, but the restriction is intentionally not communicated to the user.

Note: This status is rarely used.

Recommended action: Treat this status similarly to banned.

`review`

The user is currently under review.

During this period, the user's activity is being assessed to determine whether further action is required.

Recommended action: Hold any real-money payouts until an active callback is received.

`on_hold`

The user is currently under review, and conversions associated with the user may be placed on hold until the review process has been completed.

Recommended action: Hold any real-money payouts until an active callback is received.

Ban Duration

The [%BAN:UNTIL%] macro indicates when the current status is expected to end.

The timestamp is always provided in UTC using the ISO 8601 format.
An empty value indicates that no expiration date is currently defined.
Users without an expiration date may still be manually reinstated at a later point. In such cases, an active callback will be sent.

Examples

Value	Meaning
`2026-06-30T15:00:00Z`	The status is expected to remain in effect until the specified UTC timestamp.
(empty)	No expiration date is currently defined.

Ban Reasons

The [%BAN:REASON%] macro contains a plain-text explanation related to the user's current status.

This field is intended primarily for internal logging, fraud analysis, and customer support workflows. Publishers should avoid displaying the exact reason directly to end users whenever possible.

Note: Publishers should not rely on [%BAN:REASON%] for automated business logic. Instead, use [%BAN:STATUS%] to determine how your system should respond.

Callback Behavior

Ban callbacks are sent only when the user's status changes.
Each callback refers to exactly one demand type.
When a user is reinstated, an active callback will be sent.
A user may receive separate callbacks for different demand types.

Example Callback URL

https://publisher.example/callback?user_id=[%USER:UID%]&type=[%BAN:TYPE%]&status=[%BAN:STATUS%]&reason=[%BAN:REASON%]&until=[%BAN:UNTIL%]

Example Callbacks

User Banned from Surveys

https://publisher.example/callback?user_id=12345&type=surveys&status=banned&reason=Suspicious activity detected&until=2026-06-30T15:00:00Z

User Placed Under Review for Offers

https://publisher.example/callback?user_id=12345&type=offers&status=review&reason=Manual review initiated&until=

User Reinstated After Review

https://publisher.example/callback?user_id=12345&type=surveys&status=active&reason=Review completed&until=

Recommended Publisher Handling

Status	Recommended Action
`active`	Allow access to the affected demand type and resume normal payout processing.
`banned`	Prevent access to the affected demand type.
`shadow_ban`	Treat similarly to `banned`.
`review`	Hold real-money payouts until an `active` callback is received.
`on_hold`	Hold real-money payouts until an `active` callback is received.

By implementing ban callbacks, publishers can ensure that user access and payout handling remain aligned with the user's current status within BitLabs.