Skip to main content
Bring Your Own Screening Check lets you add a manual review step to Fireblocks transaction screening. After automatic AML screening completes, eligible transactions pause for your verdict before Travel Rule processing begins. For a conceptual overview, see Bring Your Own Screening Check (requires Help Center login).

​
Quickstart

Follow these steps to set up and activate Bring Your Own Screening Check:
  1. Contact your Customer Success Manager to enable the feature for your workspace.
  2. Configure incoming and outgoing timeouts with PUT /v1/screening/byork/config/timeouts.
  3. Open a support ticket to configure your pre-screening rules.
  4. Set up your webhook listener for screening events.
  5. Test your verdict API integration in the sandbox environment.
  6. Activate the feature with POST /v1/screening/byork/config/activate.
  7. Monitor verdict submission latency against your configured timeouts.

​
Configuration

​
Get current configuration

GET /v1/screening/byork/config
Returns your current configuration, including timeouts and active status.

​
Response example

{
  "active": false,
  "incomingTimeoutSeconds": 3600,
  "outgoingTimeoutSeconds": 3600,
  "provider": "BYORK_LITE",
  "lastUpdate": "2026-03-01T00:00:00.000Z",
  "timeoutRangeIncoming": { "minSeconds": 10, "maxSeconds": 604800 },
  "timeoutRangeOutgoing": { "minSeconds": 10, "maxSeconds": 604800 }
}
FieldTypeDescription
activebooleanWhether the feature is currently active for your tenant
incomingTimeoutSecondsnumberVerdict timeout for incoming transactions (seconds)
outgoingTimeoutSecondsnumberVerdict timeout for outgoing transactions (seconds)
preScreeningRulesarrayConfigured pre-screening rules. See Pre-screening rules reference.
providerstringProvider identifier (e.g., BYORK_LITE)
lastUpdatestringISO 8601 timestamp of the last configuration update
timeoutRangeIncomingobjectValid min/max bounds for incomingTimeoutSeconds
timeoutRangeOutgoingobjectValid min/max bounds for outgoingTimeoutSeconds

​
Set timeouts

Configure how long the system waits for your verdict before auto-rejecting a transaction. Timeouts are set separately for incoming and outgoing transactions. Always submit your verdict before the timeout expires. Once the timeout is reached, Fireblocks automatically rejects the transaction and the rejection cannot be reversed.

​
Request

PUT /v1/screening/byork/config/timeouts
Include at least one of incomingTimeoutSeconds or outgoingTimeoutSeconds in the request body. The response returns the full updated configuration.

​
Response example

{
  "incomingTimeoutSeconds": 7200,
  "outgoingTimeoutSeconds": 3600
}
ParameterDefaultMinMax
incomingTimeoutSeconds360010604800 (7 days)
outgoingTimeoutSeconds360010JWT lifetime − 1800s

​
Configure pre-screening rules

Pre-screening rules determine which transactions are held for review and which bypass the check. Rules are evaluated in order — the first match wins. Omitted fields match any value. To configure or update your pre-screening rules, open a support ticket. See Pre-screening rules reference for the full list of available rule fields.

​
Activate and deactivate

Once your timeouts and rules are set, activate to start screening transactions: 
POST /v1/screening/byork/config/activate
To pause screening without removing your configuration: 
POST /v1/screening/byork/config/deactivate
Both endpoints return the full updated configuration. When deactivated, all transactions bypass the review step and continue to Travel Rule or completion.

​
Submitting verdicts

​
Submit a verdict

POST /v1/screening/byork/verdict
Use an idempotency key on POST verdict to avoid duplicate submissions.

​
Request body

{
  "txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
  "verdict": "ACCEPT"
}
FieldTypeDescription
txIdstringFireblocks transaction ID
verdictstringACCEPT or REJECT

​
Response example

{
  "status": "COMPLETED",
  "message": "Verdict ACCEPT applied"
}

​
Get verdict status

GET /v1/screening/byork/verdict?txId={txId}
Returns the current verdict status for a transaction.
StatusDescription
PRE_ACCEPTEDVerdict submitted before the wait step was reached; applied automatically
PENDINGThe transaction is waiting for a verdict
RECEIVEDVerdict received and being applied
COMPLETEDVerdict applied; transaction continues

​
Pre-acceptance

You can submit a verdict before a transaction reaches the review wait step — for example, while automatic AML screening is still running. Fireblocks stores the verdict and applies it automatically when the transaction reaches the waiting state. This is useful when you have already completed your own review and want to avoid any delay.

​
Request

POST /v1/screening/byork/verdict

​
Response example

{
  "txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
  "verdict": "ACCEPT"
}
The response returns "status": "PRE_ACCEPTED" if the transaction has not reached the wait step yet.

​
Error handling

HTTP statusMeaningAction
400 Bad RequestBring Your Own Screening Check not enabled for tenant, or invalid payloadCheck that the feature is enabled and the request body is correct
404 Not FoundNo verdict found for this transaction (GET only)Verify txId is correct and the transaction has reached the screening step
409 ConflictVerdict already submitted, or transaction screening is completeDo not retry; verdict is final
425 Too EarlyTransaction not found yet; screening has not startedRetry after a short delay

​
Pre-screening rules reference

Rules are evaluated in order. The first matching rule determines whether the transaction is held for review (SCREEN) or bypasses it (PASS).
FieldTypeDescription
sourceWorkspaceNamestringSource workspace name. For incoming transactions.
destWorkspaceNamestringDestination workspace name. For outgoing transactions.
sourceTypestringSource address type (e.g., VAULT_ACCOUNT, EXCHANGE).
sourceSubTypestringSource address sub-type.
sourceAddressstringSource on-chain address.
sourceIdstringID of the source vault, exchange account, or unmanaged wallet.
destTypestringDestination address type.
destSubTypestringDestination address sub-type.
destAddressstringDestination on-chain address.
destIdstringID of the destination vault, exchange account, or unmanaged wallet.
assetstringAsset ID (e.g., BTC, ETH).
amountobjectAmount range with currency. See Amount object.
operationstringTransaction operation type.
directionstringINBOUND or OUTBOUND. Limits the rule to one direction.
isDefaultbooleanWhen true, applies when no other rule matches.
actionstringRequired. PASS (skip review) or SCREEN (hold for verdict).

​
Amount object

{
  "range": {
    "min": "1000",
    "max": "50000"
  },
  "currency": "USD"
}
currency is either "USD" (fiat-equivalent value) or "NATIVE" (on-chain amount). min and max are both optional.