> ## 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. # Get an importer profile > Get one importer's monthly container history, ports of discharge, origin countries, carriers, destination states, and HS4 commodities from US import bill-of-lading records. ## OpenAPI ````yaml post /trade_intel/companies/profile 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/companies/profile: post: tags: - Trade Intelligence summary: Get an importer profile description: >- Import profile for one company from US import bill-of-lading records (US Customs vessel manifests): totals (containers as consignee and as notify party, TEUs), a monthly series, ports of discharge, origin countries, carriers, destination states, and HS4 headings with estimated value. `company_name` must be the exact normalized name returned by `companies/search`. The period is `months` full calendar months ending last month, so the current, partial month is excluded; use `months: 24` or more to compare a year against the same months a year earlier. Volume is physical containers, each counted once. Estimated values are modelled USD estimates, not declared customs values. A company's figures are a floor: related entities and alternative names are separate companies, and importers can have their names withheld from manifests. Carrier names are as spelled on manifests; merge variants before computing shares. operationId: post-trade-intel-companies-profile requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelCompanyProfileRequest' examples: One state, 12 months: value: company_name: CATERPILLAR company_state: IL All states, two years: value: company_name: CATERPILLAR months: 24 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelCompanyProfile' example: company_name: EXAMPLE OUTDOOR SUPPLY company_state: null since: 2025-10 until: 2026-09 found: true totals: containers: 1240 containers_as_consignee: 1180 containers_as_notify_party: 60 teus: 2310.5 states: - GA - CA monthly: - month: 2025-10 containers: 95 teus: 180 - month: 2025-11 containers: 110 teus: 205.5 ports_of_discharge: - name: SAVANNAH containers: 900 teus: 1700 origin_countries: - name: VIETNAM containers: 700 teus: 1300 carriers: - name: MAERSK LINE containers: 500 teus: 950 destination_states: - name: GA containers: 900 teus: 1700 commodities_hs4: - hs4: '9401' description: Seats (other than barber, dental, etc), and part containers: 800 estimated_value: 31000000 notes: - >- volume is physical containers, each counted once even when it appears on several bills - the period covers full calendar months ending last month '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: TradeIntelCompanyProfileRequest: type: object properties: company_name: type: string description: Exact `company_name` from `companies/search`. minLength: 1 maxLength: 200 example: CATERPILLAR company_state: type: string description: Restrict to one state; omit for all states. maxLength: 2 example: IL nullable: true months: type: integer description: >- Full calendar months ending last month. Use 24 or more for a year-over-year view. minimum: 1 maximum: 60 default: 12 required: - company_name TradeIntelCompanyProfile: type: object properties: company_name: type: string description: The requested company name. example: CATERPILLAR company_state: type: string description: The requested state, or `null` for all states. nullable: true since: type: string description: First month of the period (inclusive). example: 2025-10 until: type: string description: Last month of the period (inclusive). example: 2026-09 found: type: boolean description: >- `false` when the exact name has no volume in the period. The name must match `companies/search` exactly; a company can also be split across several names. totals: $ref: '#/components/schemas/TradeIntelCompanyProfileTotals' monthly: type: array items: $ref: '#/components/schemas/TradeIntelMonthlyVolume' description: Volume per month, oldest first. ports_of_discharge: type: array items: $ref: '#/components/schemas/TradeIntelNamedVolume' description: US ports of discharge. origin_countries: type: array items: $ref: '#/components/schemas/TradeIntelNamedVolume' description: Origin countries. carriers: type: array items: $ref: '#/components/schemas/TradeIntelNamedVolume' description: >- Ocean carriers as spelled on manifests. Merge spelling variants before computing shares. destination_states: type: array items: $ref: '#/components/schemas/TradeIntelNamedVolume' description: Destination US states. commodities_hs4: type: array items: $ref: '#/components/schemas/TradeIntelCommodityVolume' description: HS4 headings with estimated value. notes: type: array items: type: string description: >- Counting caveats that apply to this response, for example that volume is physical containers or that the window includes a partial month. Surface these to end users. required: - company_name - company_state - since - until - found description: >- Import profile for one company. When `found` is `true` the totals, monthly series, breakdowns, and notes are returned. TradeIntelCompanyProfileTotals: type: object properties: containers: type: integer description: Physical containers in the period. containers_as_consignee: type: integer description: Containers where the company is the consignee. containers_as_notify_party: type: integer description: Containers where the company is the notify party. teus: type: number description: Twenty-foot equivalent units. states: type: array items: type: string description: US states the company's rows are split across. required: - containers - containers_as_consignee - containers_as_notify_party - teus - states TradeIntelMonthlyVolume: type: object properties: month: type: string description: Calendar month. example: 2026-03 containers: type: integer description: Physical containers. teus: type: number description: Twenty-foot equivalent units. required: - month - containers - teus TradeIntelNamedVolume: type: object properties: name: type: string description: Port, country, carrier, or state name as spelled on manifests. containers: type: integer description: Physical containers. teus: type: number description: Twenty-foot equivalent units. required: - name - containers - teus TradeIntelCommodityVolume: type: object properties: hs4: type: string description: 4-digit HS heading. example: '9401' description: type: string description: >- HS heading description. Descriptions are truncated; check `common_goods` from `commodities/search` before relying on one. containers: type: integer description: Physical containers carrying this heading. estimated_value: type: number description: Modelled USD estimate, not declared customs value. required: - hs4 - description - containers - estimated_value 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.