border.bot
Docs menu

API reference

API reference

Find an agency product code

POST https://api.border.bot/v1/classify/regulator

Requires an API key (Authorization: Bearer bb_live_…).

The product code the destination’s import agency asks for, in that agency’s coding scheme: for the US, FDA’s import product code (e.g. 16AYN07) for foods, drugs, devices, cosmetics and other goods FDA regulates. The answer names the agency and scheme, lists the code’s parts in order, and says whether the agency’s own check accepted it. Costs 1 credit; goods the agency doesn’t regulate are refused (details.reason: "not_regulated", with details.agency) and refunded.

API key scope: classify.

Headers#

Name Type Required Description
idempotency-key string no Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).

Request body (JSON)#

Name Type Required Description
description string yes What the product is, what it is made of, and how it is processed or packed (frozen, smoked, canned…).
destinationCountry string yes Where the goods are imported. Its import agency and coding scheme follow from it (for US, FDA’s import product codes).
hsCode string no The goods’ tariff code, when known: a hint for the product pick.

Responses#

  • 200: The agency product code and the credits charged. (RegulatorClassifyResponse)
  • 400: Invalid input (invalid_input). (Error)
  • 401: Missing, invalid, revoked or expired API key (unauthorized). (Error)
  • 402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
  • 403: Workspace suspended, action disabled, or the key lacks the scope (org_suspended, action_disabled, forbidden). (Error)
  • 409: A request with this Idempotency-Key is still in progress (conflict). (Error)
  • 422: No agency product codes for this destination yet (unsupported_country). (Error)
  • 429: Rate limited (rate_limited). Retry after Retry-After seconds; RateLimit says which limit was hit (r=0, t seconds until its window ends) and RateLimit-Policy its quota. (Error)
  • 500: Unexpected error (internal). (Error)
  • 502: The engine failed (upstream_error). The credits are refunded automatically. (Error)
  • 504: The engine timed out (upstream_timeout). The credits are refunded automatically. (Error)

Example#

bash
curl -X POST 'https://api.border.bot/v1/classify/regulator' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"description":"<string>","destinationCountry":"<string>"}'