Risks API

The Risks API provides monitoring for non-closure risks in transit and export declarations. Non-closure occurs when declarations are not finalized within expected timeframes, potentially triggering customs investigations or guarantee claims.

Required Scope: guarantees:read (risks are grouped under guarantees scope)

Non-Closure Risk Overview

Get aggregated counts of transit and export declarations by risk level.


curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Response


{
  "transit": {
    "total": 45,
    "low": 30,
    "medium": 10,
    "high": 5
  },
  "export": {
    "total": 22,
    "low": 15,
    "medium": 5,
    "high": 2
  },
  "summary": {
    "total_at_risk": 67,
    "requires_immediate_action": 7
  }
}

Non-Closure Risk Items

Get a paginated list of declarations at risk of non-closure with details.


curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure/items?risk_level=high&type=transit" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type: `transit`, `export`, or `all` (default: all)
`risk_level`	string	Filter by risk level: `low`, `medium`, `high`
`customer_code`	string	Filter by customer code
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Response


{
  "data": [
    {
      "id": 5001,
      "type": "transit",
      "lrn": "26NL00001234567890123",
      "mrn": "26NL12345678901234567",
      "status": "ACC",
      "customer_code": "CUST001",
      "customer_name": "Example B.V.",
      "office_of_departure": "NL000396",
      "office_of_destination": "BE123456",
      "submitted_at": "2026-03-10T09:00:00.000000Z",
      "days_open": 15,
      "risk_level": "high",
      "risk_reason": "Transit accepted but no arrival notification after 7+ days",
      "recommended_action": "Contact carrier for arrival status and submit IE007",
      "reserved_guarantee": 10000.00
    },
    {
      "id": 12350,
      "type": "export",
      "reference": "EXP-2026-050",
      "mrn": "26NL98765432109876543",
      "status": "ACC",
      "customer_code": "CUST002",
      "customer_name": "Another Company B.V.",
      "office_of_exit": "NLRTM",
      "destination_country": "GB",
      "submitted_at": "2026-03-01T14:00:00.000000Z",
      "days_open": 24,
      "risk_level": "high",
      "risk_reason": "Export accepted but no exit confirmation after 15+ days",
      "recommended_action": "Submit alternative proof of export (APE)",
      "reserved_guarantee": 8500.00
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 7
  }
}

Risk Levels

Transit (DVA) Risk Levels

Risk Level	Days Open	Description
`low`	0-2 days	Normal transit time
`medium`	3-6 days	Approaching risk threshold
`high`	7+ days	Non-closure risk, action required

Thresholds:

Low: Accepted transit, 0-2 days since departure
Medium: 3-6 days without arrival notification
High: 7+ days without arrival notification

Export Risk Levels

Risk Level	Days Open	Description
`low`	0-6 days	Normal export processing time
`medium`	7-14 days	Approaching risk threshold
`high`	15+ days	Non-closure risk, action required

Thresholds:

Low: Accepted export, 0-6 days since submission
Medium: 7-14 days without exit confirmation
High: 15+ days without exit confirmation

Risk Reasons

Transit Risk Reasons

Reason	Description	Recommended Action
No arrival notification	Departure accepted but no IE007 received	Contact carrier, submit arrival
Enquiry pending	IE140 enquiry received from customs	Respond to enquiry with IE141
Unloading incomplete	Arrival submitted but unloading not confirmed	Submit unloading remarks
Amendment pending	IE013 amendment submitted, awaiting response	Follow up with customs office

Export Risk Reasons

Reason	Description	Recommended Action
No exit confirmation	Export accepted but no exit from EU	Submit alternative proof of export (APE)
Document control	Held for document verification	Provide requested documents
Physical control	Goods held for inspection	Coordinate with carrier for inspection

Recommended Actions

Transit Actions

Submit Arrival (IE007): If goods have arrived at destination
Respond to Enquiry (IE141): If customs enquiry received
Submit Unloading Remarks: If arrival submitted but unloading not confirmed
Contact Carrier: If unsure of goods location
Request Invalidation (IE014): If transit cancelled

Export Actions

Submit APE (Alternative Proof of Export): CMR, B/L, or AWB showing exit
Provide Documents: Submit requested certificates or permits
Contact Carrier: Verify goods left EU customs territory
Request Invalidation: If export cancelled

Example: Monitor High-Risk Items Daily


# Get all high-risk items requiring immediate action
curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure/items?risk_level=high" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Process each item:

For Transit:


# Submit arrival notification
curl -X POST "https://app.borderbolt.com/api/v1/transit/5001/submit-arrival" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "arrival_date": "2026-03-24T14:30:00",
    "unloading_remarks": "All packages received intact"
  }'

For Export:


# Submit alternative proof of export
curl -X POST "https://app.borderbolt.com/api/v1/declarations/12350/ape" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "proof_type": "cmr",
    "reference": "CMR-2026-050",
    "exit_date": "2026-03-02",
    "exit_office": "NLRTM"
  }'

Financial Impact

Non-closure risks directly impact guarantee utilization:


{
  "customer_code": "CUST001",
  "total_guarantee": 200000.00,
  "reserved_at_risk": 35000.00,
  "high_risk_items": 3,
  "potential_guarantee_claim": 15000.00
}

If high-risk items are not resolved:

Customs may claim guarantee amounts
Guarantee capacity remains locked
New declarations may be blocked
Customer may face penalties or investigations

Integration with Guarantees API

Use together with Guarantees API for complete risk monitoring:


# 1. Check guarantee utilization
curl -X GET "https://app.borderbolt.com/api/v1/guarantees/dva/CUST001" \
  -H "Authorization: Bearer your-access-token"
 
# 2. Check non-closure risks
curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure/items?customer_code=CUST001" \
  -H "Authorization: Bearer your-access-token"

Combined Risk Assessment:

High guarantee utilization (>85%) + High non-closure risks = Critical customer
Normal utilization + High non-closure risks = Operational issue
High utilization + No risks = Capacity constraint

Automation Best Practices

Daily Monitoring


# Morning: Get summary
curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure"
 
# Get high-risk items
curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure/items?risk_level=high"
 
# Process each item according to recommended actions

Weekly Review


# Get all medium-risk items
curl -X GET "https://app.borderbolt.com/api/v1/risks/non-closure/items?risk_level=medium"
 
# Proactively contact customers before items escalate to high risk

Next Steps

Guarantees API - Monitor guarantee capacity
Transit API - Submit arrivals and enquiry responses
Declaration Lifecycle API - Submit APE for exports
Webhooks - Receive real-time status updates