canonical: https://jentic.com/apis/bic-boxtech.org/bic-boxtech

# BIC-BoxTech API

BIC-BoxTech is the API for the Bureau International des Containers (BIC) Global Container Database, the authoritative registry of intermodal shipping containers. It exposes container technical details (dimensions, tare weight, maximum gross mass, ISO size-type code), BIC code holder lookups for owner identification, fleet upload for container operators, and alerting on container number changes. Authentication uses an OAuth2-style bearer token obtained from `/oauth/token`, with HTTP Basic supported as a secondary scheme. Both production (app.bic-boxtech.org) and UAT (uat.bic-boxtech.org) hosts are exposed.

## For AI agents

Look up shipping container technical details, verify BIC code ownership, and upload fleet data via the BIC Global Container Database.

## Scope

Does not handle parcel tracking, customs clearance, or freight quoting - use for intermodal container identity and technical detail lookup only.

## Capabilities

- Look up the technical details for a specific container number
- Verify the holder of a BIC owner code for ownership confirmation
- Retrieve a container's tare weight and maximum gross mass in kilograms
- Resolve an ISO 6346 size-type code to its container specification
- Upload fleet data on behalf of a container operator
- Create and deactivate alerts on container records
- Browse historical fleet upload files for audit purposes

## Use cases

### Container Specification Lookup

Resolve a container number to its full technical specification at receipt or dispatch. GET `/container/{containerNumber}` returns the container record including ISO size-type code, tare weight, and maximum gross mass. Operators use this to verify physical handling characteristics before loading and to confirm ownership when accepting containers from other carriers.

Example prompt: Call `/container/MSCU1234567` and return tare weight, max gross mass, and ISO size-type code.

### BIC Code Ownership Verification

Confirm the owner of a BIC code (the four-letter prefix on every intermodal container) before accepting a container into a yard or onto a vessel. GET `/codes/{bicCode}` returns the registered holder, which protects against fraudulent or expired codes. Combined with the container details endpoint this gives a complete identity check.

Example prompt: Call `/codes/MSCU` and return the registered holder name and contact details.

### Fleet Data Upload for Container Operators

Submit fleet inventory updates on behalf of a container operator so the global database reflects newly registered or reassigned containers. POST /container accepts the upload payload, and GET `/uploads/{uploadId}` returns the processing status. This is required for operators that want their fleet visible to global counterparties.

Example prompt: Upload a CSV of 500 new containers via POST /container and poll GET `/uploads/{uploadId}` until processing completes.

### AI Agent Container Intake Assistant

An AI agent helping a port operator intake containers can verify ownership and pull technical specifications in a single workflow. Through Jentic the agent searches for 'verify container BIC code' and 'get container details', loads each schema, and executes - Jentic injects the bearer token so the agent never handles raw operator credentials.

Example prompt: Search Jentic for 'look up a container by number', execute `/container/MSCU1234567`, and confirm the holder via `/codes/MSCU.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/oauth/token` | Obtain an access token |
| GET | `/codes/{bicCode}` | Look up a BIC code holder |
| POST | `/container` | Upload container fleet data |
| GET | `/container/{containerNumber}` | Get container technical details |
| GET | `/tare_kg/{containerNumber}` | Get tare weight in kilograms |
| GET | `/iso/size_type_code/{sizeTypeCode}` | Look up an ISO size-type code |

## Key resources

- **Container** — Retrieve, upload, and remove container records by number
- **BIC codes** — Look up the registered holder of a BIC owner code
- **ISO size-type** — Resolve ISO 6346 size-type codes to container specifications
- **Alerts** — Manage alerts on container record changes
- **Uploads** — Browse and retrieve historical fleet upload files

## Why Jentic

- **Setup:** Wiring the BIC-BoxTech API by hand means exchanging credentials at `/oauth/token` for a bearer token, optionally falling back to basic auth, and building container lookup paths yourself. Through Jentic you install once, import BIC-BoxTech from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** BIC-BoxTech puts the container number in the URL path (`/container/{containerNumber}`, `/tare_kg/{containerNumber}`), so a rule can pin your agent to lookups for a given container. You choose the operations it may call, so container registration is not included unless you add it.
- **Credential handling:** Your BIC-BoxTech bearer token, and any basic-auth credentials, are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a container by number' or 'get a container's tare weight', and Jentic returns the matching BIC-BoxTech operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AfterShip API** — AfterShip tracks parcel and container movements after their identity has been verified via BIC-BoxTech.
- **Shippo API** — Shippo handles parcel-level shipping labels for last-mile movement around containerised freight.
- **FedEx API** — FedEx tracks shipments at the parcel and freight level; BIC-BoxTech focuses on container identity rather than transit.

## FAQ

### What authentication does the BIC-BoxTech API use?

BIC-BoxTech supports two schemes: HTTP Bearer (the recommended scheme - obtain the access token from POST `/oauth/token`) and HTTP Basic. Through Jentic, the bearer token is stored encrypted in the your Jentic One instance and injected at execution time so the agent never sees the raw token.

### Can I look up a container by its container number?

Yes. GET `/container/{containerNumber}` returns the technical record including tare weight, maximum gross mass, and ISO 6346 size-type code. You can also use GET `/tare_kg/{containerNumber}` or GET `/max_gross_mass_kgs/{containerNumber}` to fetch specific properties without loading the full record.

### How do I verify a BIC owner code?

Call GET `/codes/{bicCode}` with the four-letter BIC prefix. The response includes the registered holder details, which lets you confirm the container's ownership before accepting it into your yard or onto a vessel.

### How do I upload fleet data through Jentic?

Search Jentic for 'upload container fleet', load POST /container, and execute with the upload payload. Then poll GET `/uploads/{uploadId}` until processing completes. With the SDK: pip install jentic, then SearchRequest, LoadRequest, ExecutionRequest in an async flow.

### Is there a sandbox environment for the BIC-BoxTech API?

Yes - the spec exposes a UAT host at https://uat.bic-boxtech.org/api/v2.0 alongside production at https://app.bic-boxtech.org/api/v2.0. Use UAT for integration testing before promoting to production credentials.

### Can I limit what my agent is allowed to do with the BIC-BoxTech API?

Yes. Because you run Jentic One yourself, your own rules decide which BIC-BoxTech operations and credentials the agent may use. You can allow read-only lookups such as GET `/container/{containerNumber}`, GET `/tare_kg/{containerNumber}`, and GET `/codes/{bicCode}` while withholding fleet registration via POST /container, so container uploads are excluded unless you add them. Since the container number sits in the URL path, a rule can also pin the agent to lookups for a specific container.