Rejection Analysis API

The Rejection Analysis API provides comprehensive data about declaration rejections, error codes, affected fields, and rejection trends.

Required Scope: declarations:read

Get Summary Data

Retrieve complete rejection analysis data including all metrics, trends, and breakdowns.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/summary?period=this_month" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)

Period Values

today - Today only
this_week - Monday to present
this_month - 1st of month to present
last_30_days - Rolling 30-day window
last_60_days - Rolling 60-day window
last_90_days - Rolling 90-day window
this_year - January 1st to present

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "summary": {
    "total_submissions": 142,
    "rejections": 8,
    "rejection_rate": 5.6,
    "unique_error_codes": 12
  },
  "trend": [
    {
      "date": "2026-04-01",
      "label": "Apr 01",
      "submissions": 15,
      "rejections": 1,
      "rate": 6.7
    }
  ],
  "top_error_codes": [
    {
      "error_code": "DMS343AA",
      "count": 23,
      "description": "Invalid address or country code",
      "affected_fields": ["consignee_country", "destination_country"]
    }
  ],
  "affected_fields": [
    {
      "db_field": "consignee_country",
      "count": 18
    }
  ],
  "by_type": {
    "import": {
      "count": 52,
      "percentage": 65.0
    },
    "export": {
      "count": 20,
      "percentage": 25.0
    },
    "transit": {
      "count": 8,
      "percentage": 10.0
    }
  },
  "recent_rejections": [
    {
      "id": 123,
      "declaration_id": 456,
      "reference": "ABC-2024-001234",
      "customer": "Acme Corp",
      "type": "H1",
      "date": "17 Apr 2026",
      "errors": 3,
      "status": "pending",
      "status_label": "Pending",
      "status_color": "yellow"
    }
  ]
}

Get Top Error Codes

Retrieve the most frequent error codes with counts and descriptions.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/top-error-codes?period=this_month&limit=10" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)
`limit`	No	integer	Number of results (default: 10)

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "error_codes": [
    {
      "error_code": "DMS343AA",
      "count": 23,
      "description": "Invalid address or country code",
      "affected_fields": ["consignee_country", "destination_country"]
    },
    {
      "error_code": "TMSV0045",
      "count": 14,
      "description": "Missing required document",
      "affected_fields": ["document_code"]
    }
  ]
}

Get Affected Fields

Retrieve fields that most frequently cause rejections.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/affected-fields?period=this_month&limit=10" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)
`limit`	No	integer	Number of results (default: 10)

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "fields": [
    {
      "db_field": "consignee_country",
      "count": 18
    },
    {
      "db_field": "document_code",
      "count": 12
    },
    {
      "db_field": "procedure_code",
      "count": 8
    }
  ]
}

Get Rejections by Type

Retrieve rejection breakdown by declaration type (import/export/transit).


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/by-type?period=this_month" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "breakdown": {
    "import": {
      "count": 52,
      "percentage": 65.0
    },
    "export": {
      "count": 20,
      "percentage": 25.0
    },
    "transit": {
      "count": 8,
      "percentage": 10.0
    }
  }
}

Get Declarations by Error Code

Retrieve all declarations affected by a specific error code.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/error-codes/DMS343AA/declarations?period=this_month" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Path Parameters

Parameter	Required	Type	Description
`errorCode`	Yes	string	Error code to filter by

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "error_code": "DMS343AA",
  "description": "Invalid address or country code",
  "declarations": [
    {
      "id": 789,
      "declaration_id": 456,
      "reference": "ABC-2024-001234",
      "customer": "Acme Corp",
      "type": "H1",
      "error_code": "DMS343AA",
      "db_field": "consignee_country",
      "original_value": "XX",
      "line_number": 3,
      "error_pointer": "Declaration/GoodsShipment[1]/Consignment/Consignee/Address/CountryCode",
      "date": "12 Apr 2026",
      "is_resolved": false
    }
  ]
}

Get Recent Rejections

Retrieve the most recent rejections.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/recent-rejections?limit=10" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`limit`	No	integer	Number of results (default: 10)

Response


{
  "rejections": [
    {
      "id": 123,
      "declaration_id": 456,
      "reference": "ABC-2024-001234",
      "customer": "Acme Corp",
      "type": "H1",
      "date": "17 Apr 2026",
      "errors": 3,
      "status": "pending",
      "status_label": "Pending",
      "status_color": "yellow"
    },
    {
      "id": 124,
      "declaration_id": 457,
      "reference": "DEF-2024-005678",
      "customer": "XYZ Ltd",
      "type": "B1",
      "date": "16 Apr 2026",
      "errors": 1,
      "status": "resolved",
      "status_label": "Resolved",
      "status_color": "green"
    }
  ]
}

Get Rejection Trend

Retrieve rejection rate trend data over time.


curl -X GET "https://app.borderbolt.com/api/v1/rejection-analysis/trend?period=this_month" \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Query Parameters

Parameter	Required	Type	Description
`period`	No	string	Time period (default: `this_month`)

Response


{
  "period": "this_month",
  "date_from": "2026-04-01T00:00:00+00:00",
  "date_to": "2026-04-17T14:30:00+00:00",
  "trend": [
    {
      "date": "2026-04-01",
      "label": "Apr 01",
      "submissions": 15,
      "rejections": 1,
      "rate": 6.7
    },
    {
      "date": "2026-04-02",
      "label": "Apr 02",
      "submissions": 18,
      "rejections": 0,
      "rate": 0.0
    },
    {
      "date": "2026-04-03",
      "label": "Apr 03",
      "submissions": 12,
      "rejections": 2,
      "rate": 16.7
    }
  ]
}

For periods longer than 90 days, the trend data uses weekly granularity instead of daily.

Common Error Codes

Some frequently encountered error codes:

Code	Description	Common Fields
DMS343AA	Invalid address or country code	consignee_country, destination_country
TMSV0045	Missing required document	document_code
DMS548AA	Invalid procedure code	procedure_code
DMS372AA	Missing destination country	destination_country
DMS653AA	Invalid government procedure	additional_procedure
DMS455AA	Invalid country code	Various country fields
DMS869AB	Declarant EORI not authorized	eori_number
DMS255AB	TARIC code required	commodity_code

Error descriptions are retrieved from the customs codebook and may vary by country and language.

Error Handling

Standard error responses apply. See Error Reference for details.

Common Errors

Status Code	Error Code	Description
401	`unauthorized`	Invalid or missing access token
403	`forbidden`	Missing `declarations:read` scope
400	`invalid_period`	Invalid period parameter

Rate Limits

Rate Limit: 100 requests per minute per token
Burst Limit: 200 requests per minute
Rate limit headers are included in all responses

See Authentication for more details.