Guarantees API

The Guarantees API provides read-only access to surety guarantee balances (import/export) and DVA guarantee balances (transit), with risk level indicators and per-declarant breakdowns.

Required Scope: guarantees:read

Surety Guarantee Overview

Get aggregated surety balance across all declarants (used for DMS import/export declarations).


GET /api/v1/guarantees/surety


curl https://app.borderbolt.com/api/v1/guarantees/surety \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "level": "normal",
    "usage_percentage": 34.0,
    "available_import": 80000.00,
    "available_export": 85000.00,
    "in_processing": 5000.00,
    "total_available": 165000.00,
    "total_limit": 250000.00,
    "used": 85000.00,
    "available": 165000.00,
    "currency": "EUR",
    "warning_threshold": 70,
    "critical_threshold": 90,
    "last_synced_at": "2026-05-04T08:00:00+00:00",
    "declarant_count": 2,
    "declarants": [
      {
        "customer_code": "CUST001",
        "customer_name": "Example B.V.",
        "level": "normal",
        "usage_percentage": 35.0,
        "available_import": 35000.00,
        "available_export": 30000.00,
        "in_processing": 0.00,
        "total_available": 65000.00,
        "currency": "EUR",
        "sync_status": "synced",
        "last_synced_at": "2026-05-04T08:00:00+00:00"
      },
      {
        "customer_code": "CUST002",
        "customer_name": "Another Company B.V.",
        "level": "critical",
        "usage_percentage": 90.0,
        "available_import": 3000.00,
        "available_export": 2000.00,
        "in_processing": 5000.00,
        "total_available": 5000.00,
        "currency": "EUR",
        "sync_status": "synced",
        "last_synced_at": "2026-05-04T08:00:00+00:00"
      }
    ]
  }
}

Surety Guarantee by Declarant

Get surety balance details for a specific declarant customer.


GET /api/v1/guarantees/surety/{customerCode}


curl https://app.borderbolt.com/api/v1/guarantees/surety/CUST001 \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "customer_code": "CUST001",
    "customer_name": "Example B.V.",
    "level": "normal",
    "usage_percentage": 35.0,
    "total_limit": 100000.00,
    "used_amount": 35000.00,
    "available_amount": 65000.00,
    "available_import": 35000.00,
    "available_export": 30000.00,
    "in_processing": 0.00,
    "total_available": 65000.00,
    "currency": "EUR",
    "warning_threshold": 70,
    "critical_threshold": 90,
    "sync_status": "synced",
    "sync_error": null,
    "last_synced_at": "2026-05-04T08:00:00+00:00"
  }
}

Not Found

HTTP 404 is returned when the customer or their surety balance does not exist.

DVA Guarantee Overview

Get aggregated DVA guarantee balance across all declarants (used for NCTS5 transit declarations).


GET /api/v1/guarantees/dva


curl https://app.borderbolt.com/api/v1/guarantees/dva \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "level": "normal",
    "usage_percentage": 25.0,
    "total_limit": 500000.00,
    "used": 125000.00,
    "available": 375000.00,
    "currency": "EUR",
    "warning_threshold": 70,
    "critical_threshold": 90,
    "last_synced_at": "2026-05-04T08:00:00+00:00",
    "declarant_count": 2,
    "declarants": [
      {
        "customer_code": "CUST001",
        "customer_name": "Example B.V.",
        "level": "normal",
        "usage_percentage": 25.0,
        "total_limit": 200000.00,
        "used_amount": 50000.00,
        "available_amount": 150000.00,
        "currency": "EUR",
        "guarantee_type": "0",
        "guarantee_type_label": "Comprehensive guarantee",
        "grn": "26NL00001234567",
        "sync_status": "synced",
        "last_synced_at": "2026-05-04T08:00:00+00:00"
      }
    ]
  }
}

DVA Guarantee by Declarant

Get DVA guarantee balance details for a specific declarant customer.


GET /api/v1/guarantees/dva/{customerCode}


curl https://app.borderbolt.com/api/v1/guarantees/dva/CUST001 \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "customer_code": "CUST001",
    "customer_name": "Example B.V.",
    "level": "normal",
    "usage_percentage": 25.0,
    "total_limit": 200000.00,
    "used_amount": 50000.00,
    "available_amount": 150000.00,
    "currency": "EUR",
    "guarantee_type": "0",
    "guarantee_type_label": "Comprehensive guarantee",
    "grn": "26NL00001234567",
    "warning_threshold": 70,
    "critical_threshold": 90,
    "sync_status": "synced",
    "sync_error": null,
    "last_synced_at": "2026-05-04T08:00:00+00:00"
  }
}

Response Field Reference

Aggregated (Overview) Fields

Field	Type	Description
`level`	string	Overall risk level: `normal`, `warning`, or `critical`
`usage_percentage`	number	Total used as percentage of total limit
`total_limit`	number	Total guarantee limit
`used`	number	Total amount in use
`available`	number	Total available (limit minus used)
`available_import`	number	Available for import declarations (surety only)
`available_export`	number	Available for export declarations (surety only)
`in_processing`	number	Amount reserved for declarations in processing (surety only)
`total_available`	number	Available including in-processing amounts (surety only)
`currency`	string	Currency code (always `EUR`)
`warning_threshold`	number	Percentage at which level becomes `warning`
`critical_threshold`	number	Percentage at which level becomes `critical`
`last_synced_at`	string	ISO 8601 timestamp of last sync with customs
`declarant_count`	integer	Number of declarants
`declarants`	array	Per-declarant balance breakdown

Per-Declarant (Detail) Fields

Field	Type	Description
`customer_code`	string	Declarant customer code
`customer_name`	string	Declarant customer name
`level`	string	Risk level: `normal`, `warning`, `critical`
`usage_percentage`	number	Used as percentage of limit
`total_limit`	number	Total guarantee limit for this declarant
`used_amount`	number	Amount currently in use
`available_amount`	number	Available (limit minus used)
`currency`	string	Currency code
`sync_status`	string	Sync status with customs: `synced`, `pending`, `error`
`sync_error`	string\|null	Error message if last sync failed
`last_synced_at`	string\|null	ISO 8601 timestamp of last successful sync
`guarantee_type`	string	DVA only — guarantee type code (0–9)
`guarantee_type_label`	string	DVA only — human-readable guarantee type
`grn`	string\|null	DVA only — Guarantee Reference Number

Risk Levels

Risk levels are calculated based on guarantee utilization percentage and the thresholds configured for your organisation:

Risk Level	Default Threshold	Description
`normal`	0–69%	Healthy guarantee capacity
`warning`	70–89%	Approaching capacity limit
`critical`	90–100%	Near or at capacity limit

Customers at critical risk level may be unable to submit new declarations or transits until existing ones are released and the guarantee balance is restored.

DVA Guarantee Types

Type Code	Description
`0`	Comprehensive guarantee (multiple operations)
`1`	Individual guarantee (single operation)
`2`	Individual guarantee in cash or equivalent
`3`	Guarantee waiver (AEO status)
`4`	Guarantee not required
`9`	Individual guarantee not required

Next Steps

Risks API — Monitor non-closure risks
Transit API — DVA guarantee usage
Declarations API — Surety guarantee usage