> ## Documentation Index > Fetch the complete documentation index at: https://terminal49-feat-trade-intel-sdk.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Look up a bill of lading > Get the import record for a master or house bill of lading from US Customs manifests: containers, consignee, shipper, notify party, and commodity lines. ## OpenAPI ````yaml post /trade_intel/bills_of_lading/lookup openapi: 3.0.0 info: title: Terminal49 API Reference version: 0.2.0 contact: name: Terminal49 API support url: https://www.terminal49.com email: support@terminal49.com description: >- The Terminal 49 API offers a convenient way to programmatically track your shipments from origin to destination. Please enter your API key into the "Variables" tab before using these endpoints within Postman. x-label: Beta termsOfService: https://www.terminal49.com/terms servers: - url: https://api.terminal49.com/v2 description: Production security: - authorization: [] tags: - name: Containers - name: Custom Field Definitions - name: Custom Field Options - name: Custom Fields - name: Shipments - name: Locations - name: Events - name: Tracking Requests - name: Webhooks - name: Webhook Notifications - name: Ports - name: Metro Areas - name: Terminals - name: Routing (Paid) - name: Documents - name: Email Submissions - name: Document Schemas - name: Search - name: Parties - name: Trade Intelligence description: >- Trade intelligence answers questions about who imports what into the US, from where, on which carriers, and how that changes over time. The data is US import bill-of-lading records (US Customs vessel manifests): every ocean container landed at a US port (plus US-bound cargo landed at Vancouver, BC) from January 2022 to today, refreshed daily. It does not include air freight, exports, or domestic moves. **Access.** Trade intelligence is enabled per account. Accounts without it receive `403 Forbidden` with `{"error": "Trade intelligence is not enabled for this account"}`; contact sales@terminal49.com to enable it. Requests are limited to roughly 120 per minute per account (`429` with `{"error": "Rate limit exceeded; retry in a minute"}`). **Format.** These endpoints accept and return plain JSON, not JSON:API. Send `Content-Type: application/json` on `POST` requests and authenticate exactly like every other v2 endpoint (`Authorization: Token YOUR_API_KEY`). **Typical flow.** Resolve a name or product first, then analyze: `companies/search` or `commodities/search` give you the exact `company_name` or `hs4` to pass to `companies/profile`, `importers/top`, `trends`, or `breakdown`. Container and bill of lading numbers go straight to `containers/lookup` and `bills_of_lading/lookup`. **Reading the numbers.** - **Volume is physical containers.** Each box is counted once, even when it appears on several bills of lading. A container carrying several HS codes counts once per code and companies can share containers, so do not add volumes across HS codes or companies; take market totals from `trends` or `breakdown` without a company filter. - **Estimated value is a modelled USD estimate**, not the declared customs value. - **The current month is partial.** `trends` and `breakdown` include it by default; `companies/profile` and `importers/top` use full calendar months. Compare full months against the same months a year earlier. - **Absent volume is not small volume.** Importers can ask US Customs to withhold their name from manifests, and much large-retail freight is booked under forwarders or suppliers. Treat a company's figures as a floor, never as its size. - **One company, many names.** Company names are normalized but split by state, and large importers use several names (distribution, merchandising, and DC entities). Related entities are separate companies; report them separately. `companies/search` ranks by match quality, not by size. - **Companies are the consignee or notify party on the bill.** Forwarders, NVOCCs, and customs brokers appear alongside cargo owners. A high notify-party share, or LOGISTICS, FREIGHT, SHIPPING, CUSTOMS, or BROKERAGE in the name, usually indicates a logistics provider. - **Carriers, countries, and ports use the manifests' spellings**, and carriers appear under spelling variants (for example `CMA CGM` and `CMA CGM AMERICA LLC`). Filter with substrings and merge variants before computing shares. - **HS4 descriptions are truncated.** Check `common_goods` from `commodities/search` before relying on a code. paths: /trade_intel/bills_of_lading/lookup: post: tags: - Trade Intelligence summary: Look up a bill of lading description: >- The import record for a master or house bill of lading from US import bill-of-lading records (US Customs vessel manifests): the containers that moved under it and the commodity lines with consignee, shipper, and notify party. The search covers the last `months` months (default 12). Up to 50 matching bill records are used (`bills_truncated`), and containers and commodity lines are each capped at 200 (`containers_truncated`, `commodities_truncated`). When nothing matches, `found` is `false` and `searched_since` tells you how far back the search went. This lookup reads record-level data and can take several seconds. operationId: post-trade-intel-bills-of-lading-lookup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelBillOfLadingLookupRequest' examples: Master bill: value: bol_number: MEDUW9559867 Longer window: value: bol_number: MEDUW9559867 months: 18 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelBillOfLadingLookup' example: bol_number: MEDUW9559867 found: true searched_since: '2025-10-01' bills_matched: 1 bills_truncated: false containers: - container_number: MSCU1234567 imported_on: '2026-08-14' scac: MSCU vessel_name: EXAMPLE VESSEL voyage_number: 026N port_of_lading_name: NINGBO port_of_discharge_name: LOS ANGELES destination_city: ONTARIO destination_state: CA container_type_short_description: 40 HC container_teu: 2 containers_truncated: false commodities: - imported_on: '2026-08-14' master_bill_of_lading_number: MEDUW9559867 house_bill_of_lading_number: null consignee: EXAMPLE OUTDOOR SUPPLY consignee_city: ONTARIO consignee_state: CA notify_party: EXAMPLE OUTDOOR SUPPLY shipper: EXAMPLE FURNITURE CO LTD shipper_country: PEOPLES REP OF CHINA commodity_short_description: OFFICE CHAIRS commodity_hs_code_6: '940130' commodity_hs_code_6_description: Swivel seats with variable height adjustment commodity_quantity: 420 commodity_quantity_uom: CTN commodity_estimated_value: 38000 bol_metric_tons: 8.2 bol_teus: 2 nvocc_scac: null nvocc_scac_description: null commodities_truncated: false '400': $ref: '#/components/responses/TradeIntelBadRequest' '401': $ref: '#/components/responses/TradeIntelUnauthorized' '403': $ref: '#/components/responses/TradeIntelNotEnabled' '422': $ref: '#/components/responses/TradeIntelValidationFailed' '429': $ref: '#/components/responses/TradeIntelRateLimited' '502': $ref: '#/components/responses/TradeIntelUnavailable' '504': $ref: '#/components/responses/TradeIntelUnavailable' components: schemas: TradeIntelBillOfLadingLookupRequest: type: object properties: bol_number: type: string description: >- Master (SCAC-prefixed) or house bill of lading number. Spaces and hyphens are removed and letters uppercased before matching. minLength: 4 maxLength: 40 example: MEDUW9559867 months: type: integer description: How many months back to search. minimum: 1 maximum: 18 default: 12 required: - bol_number TradeIntelBillOfLadingLookup: type: object properties: bol_number: type: string description: The normalized bill of lading number that was looked up. example: MEDUW9559867 found: type: boolean description: >- `false` when no import under this number is on record in the search window. searched_since: type: string description: Start of the search window. format: date example: '2025-10-01' bills_matched: type: integer description: Distinct bill of lading records matched (at most 50). bills_truncated: type: boolean description: >- `true` when more than 50 records matched and only the most recent 50 are used. containers: type: array items: $ref: '#/components/schemas/TradeIntelBillOfLadingContainer' description: Containers on the matched bills (at most 200). containers_truncated: type: boolean description: >- `true` when more than 200 containers exist and only the first 200 are returned. commodities: type: array items: $ref: '#/components/schemas/TradeIntelCommodityLine' description: >- Commodity lines on the matched bills, grouped by bill with the highest estimated value first within each bill. At most 200 lines are returned; the cap keeps the first 200 in that order, not the 200 highest-value lines overall. commodities_truncated: type: boolean description: >- `true` when more than 200 commodity lines exist and only the first 200 are returned. required: - bol_number - found - searched_since TradeIntelBillOfLadingContainer: type: object description: A container that moved under the bill of lading. properties: container_number: type: string description: ISO 6346 container number. nullable: true imported_on: type: string description: Import date. format: date nullable: true scac: type: string description: Ocean carrier SCAC. nullable: true vessel_name: type: string nullable: true voyage_number: type: string nullable: true port_of_lading_name: type: string description: Foreign port where the container was loaded. nullable: true port_of_discharge_name: type: string description: US port where the container was discharged. nullable: true destination_city: type: string nullable: true destination_state: type: string description: Two-letter US state. nullable: true container_type_short_description: type: string description: Container type. nullable: true container_teu: type: number description: TEUs of the container. nullable: true TradeIntelCommodityLine: type: object description: One commodity line from a bill of lading, with the parties on that bill. properties: imported_on: type: string description: Import date. format: date nullable: true master_bill_of_lading_number: type: string description: Carrier (master) bill of lading number. nullable: true house_bill_of_lading_number: type: string description: House bill of lading number, when the cargo moved under an NVOCC. nullable: true consignee: type: string description: Consignee name as declared on the manifest. nullable: true consignee_city: type: string nullable: true consignee_state: type: string description: Two-letter US state. nullable: true notify_party: type: string description: Notify party as declared on the manifest. nullable: true shipper: type: string description: Shipper name as declared on the manifest. nullable: true shipper_country: type: string nullable: true commodity_short_description: type: string description: Goods description from the manifest line. nullable: true commodity_hs_code_6: type: string description: 6-digit HS code assigned to the line. nullable: true commodity_hs_code_6_description: type: string nullable: true commodity_quantity: type: number description: Declared quantity. nullable: true commodity_quantity_uom: type: string description: Unit of the declared quantity. nullable: true commodity_estimated_value: type: number description: Modelled USD estimate for the line, not declared customs value. nullable: true bol_metric_tons: type: number description: Weight of the bill of lading in metric tons. nullable: true bol_teus: type: number description: TEUs on the bill of lading. nullable: true nvocc_scac: type: string description: SCAC of the NVOCC, when one filed the bill. nullable: true nvocc_scac_description: type: string description: NVOCC name. nullable: true TradeIntelError: type: object description: >- Plain JSON error body returned by trade intelligence endpoints (not JSON:API). properties: error: type: string description: >- What was wrong with the request, or why trade intelligence could not answer. example: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one required: - error TradeIntelValidationError: type: object description: >- Schema validation failure (for example a `limit` above its maximum or a malformed month). properties: detail: type: array items: type: object properties: loc: type: array items: oneOf: - type: string - type: integer description: Path to the offending field, for example `["body", "limit"]`. msg: type: string description: Human-readable validation message. type: type: string description: Validation error type, for example `less_than_equal`. required: - loc - msg - type description: One entry per field that failed schema validation. required: - detail responses: TradeIntelBadRequest: description: >- Bad Request - the request was understood but a value is invalid, for example an `hs4` that is not a 4-digit HS code. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one TradeIntelUnauthorized: description: Unauthorized - the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Terminal49 API key could not be verified TradeIntelNotEnabled: description: >- Forbidden - trade intelligence is not enabled for this account. Contact sales@terminal49.com. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is not enabled for this account TradeIntelValidationFailed: description: >- Unprocessable Entity - the body failed schema validation (a value out of range, a malformed month, or an unknown enum value). content: application/json: schema: $ref: '#/components/schemas/TradeIntelValidationError' example: detail: - loc: - body - limit msg: Input should be less than or equal to 50 type: less_than_equal TradeIntelRateLimited: description: >- Too Many Requests - about 120 requests per minute are allowed per account. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Rate limit exceeded; retry in a minute TradeIntelUnavailable: description: >- Bad Gateway or Gateway Timeout - trade intelligence is temporarily unavailable; retry shortly. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is temporarily unavailable; try again shortly securitySchemes: authorization: name: Authorization type: apiKey in: header description: >- Use a Terminal49 API key in the `Authorization` header with the `Token` prefix. `Authorization: Token YOUR_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.