OpenAPI Specification
openapi: 3.1.0
info:
title: Tradeverifyd Documents Shipments API
description: '
The Tradeverifyd API offers advanced capabilities for analyzing supply chain entities and their intricate relationships, enabling users to gain deep insights into the complex dynamics of global trade networks.
For more information visit [tradeverifyd.com](https://tradeverifyd.com).
If you have questions regarding specific use cases or how to accomplish them, please reach out to [support@tradeverifyd.com](mailto:support@tradeverifyd.com?subject=Tradeverifyd%20use%20cases) for guidance.
When making requests that require a Tradeverifyd API Key make sure the correct HTTP Header is included.
For example:
```bash
curl --silent --location -G ''https://.../v1/search/entities'' \
--data-urlencode ''name=Contoso Corporation'' \
--data-urlencode ''jurisdiction=US'' \
--header "ocp-apim-subscription-key: $TRADEVERIFYD_API_KEY"
```
'
termsOfService: https://tradeverifyd.com/terms-of-service
contact:
name: tradeverifyd.com
url: https://tradeverifyd.com/
email: support@tradeverifyd.com
license:
name: Proprietary License
url: https://tradeverifyd.com/terms-of-service
version: 0.2.0
servers:
- url: https://api.tradeverifyd.com
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Shipments
description: Operations involving shipments
paths:
/v1/shipments:
get:
tags:
- Shipments
summary: Get Shipment List
description: Get a list of shipments.
operationId: get_shipments_shipments_get
parameters:
- name: shipment_name
in: query
required: false
schema:
default: []
title: Shipment Name
type: array
items:
type: string
nullable: true
- name: status
in: query
required: false
schema:
default: []
title: Status
type: array
items:
type: string
nullable: true
- name: page
in: query
required: false
schema:
default: 1
title: Page
type: integer
nullable: true
- name: page_size
in: query
required: false
schema:
default: 25
title: Page Size
type: integer
nullable: true
- name: sorting
in: query
required: false
schema:
default: ''
title: Sorting
type: string
nullable: true
responses:
'200':
description: List of shipments with pagination
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentListingResponse'
examples:
multiple_shipments:
summary: Multiple shipments across different industries
description: Paginated list showing various shipment types and statuses across different organizational units
value:
shipments:
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
shipment_name: Cellphone Components - Q1 2024
organization: ACME_CORP
organizational_units:
- Electronics Division
- Mobile Devices
status: In Transit
active: true
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d480
shipment_name: Battery Modules - Shanghai to Fremont
organization: ACME_CORP
organizational_units:
- Automotive Division
status: Complete
active: true
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d481
shipment_name: Medical Supplies - Emergency Procurement
organization: ACME_CORP
organizational_units:
- Healthcare Division
status: Detained
active: true
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d482
shipment_name: Aerospace Components
organization: ACME_CORP
organizational_units:
- Aerospace Division
status: Created
active: true
pagination:
current_page: 1
page_size: 10
total_pages: 3
total_records: 25
filters:
shipment_name: []
status: []
sorting:
- shipment_name:asc
filtered_shipments:
summary: Filtered shipments by status
description: Shipments filtered to show only those in transit
value:
shipments:
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d483
shipment_name: Smartphone Supply Chain - Asia Pacific
organization: ACME_CORP
organizational_units:
- Electronics Division
status: In Transit
active: true
- shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d484
shipment_name: Vehicle Parts - Mexico to Detroit
organization: ACME_CORP
organizational_units:
- Automotive Division
status: In Transit
active: true
pagination:
current_page: 1
page_size: 10
total_pages: 1
total_records: 2
filters:
shipment_name: []
status:
- In Transit
sorting:
- departure_date:desc
empty_results:
summary: No matching shipments
description: Query returned no matching shipments
value:
shipments: []
pagination:
current_page: 1
page_size: 10
total_pages: 0
total_records: 0
filters:
shipment_name:
- Non-existent Shipment
status: []
sorting: []
'400':
description: Bad request - invalid parameters
content:
application/json:
examples:
no_organizational_units:
summary: User lacks organizational units
value:
detail: User does not have any organizational units
invalid_paging:
summary: Invalid paging parameters
value:
detail: Invalid Paging Parameters
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Shipments
summary: Create Shipment
description: Creates a new shipment. To update an existing shipment, use PUT /shipments/{shipment_id} instead. Supports multiple organizational units per shipment for flexible organization structure management. Auto-creates LEI and ITI credentials if organization has AUTO_CREATE_SHIPMENT_CREDENTIALS enabled.
operationId: create_shipment_shipments_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShipmentRequest'
examples:
create_electronics_shipment:
summary: Create New Electronics Shipment
description: Create new shipment for cellphone components
value:
shipment_name: 2024-Q1-Phone-Components
origin: Shenzhen, Guangdong, China
destination: Cupertino, CA, USA
departure_date: '2024-03-01T08:00:00Z'
arrival_date: '2024-03-15T16:30:00Z'
status: Created
active: true
organizational_units:
- electronics
- supply-chain
create_detained_shipment:
summary: Create Detained Shipment
description: Create medical supplies shipment with detention ID
value:
shipment_name: Med-2024-PPE-Emergency
origin: Hamburg, Germany
destination: New York, NY, USA
departure_date: '2024-03-05T06:00:00Z'
arrival_date: '2024-03-20T12:00:00Z'
status: Detained
active: true
organizational_units:
- medical
- emergency
detention_id: CBP-DET-2024-001234
minimal_shipment:
summary: Minimal Required Fields
description: Shipment with only required fields
value:
shipment_name: Basic-Shipment-2024
status: Created
organizational_units:
- default
responses:
'200':
description: Shipment created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentDetailResponse'
examples:
created_electronics_shipment:
summary: Created Electronics Shipment
description: New shipment created for smartphone components from China
value:
shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
shipment_name: 2024-Q1-Phone-Components
organization: phones-inc
organizational_unit:
- electronics
- supply-chain
folder: 2024-Q1-Phone-Components
origin: Shenzhen, Guangdong, China
destination: Cupertino, CA, USA
departure_date: '2024-03-01T08:00:00Z'
arrival_date: '2024-03-15T16:30:00Z'
status: Created
active: true
created_medical_shipment:
summary: Created Medical Shipment
description: New medical supplies shipment created with detention status
value:
shipment_id: 550e8400-e29b-41d4-a716-446655440000
shipment_name: 2024-PPE-Emergency
organization: ppe-corp
organizational_unit:
- medical
- emergency
detention_id: CBP-DET-2024-001234
folder: 2024-PPE-Emergency
origin: Hamburg, Germany
destination: New York, NY, USA
departure_date: '2024-03-05T06:00:00Z'
arrival_date: '2024-03-20T12:00:00Z'
status: Detained
active: true
'400':
description: Bad Request
content:
application/json:
examples:
duplicate_name:
summary: Duplicate shipment name
value:
detail: Shipment name already exists and no id was provided - Not unique
invalid_status:
summary: Invalid shipment status
value:
detail: Invalid shipment status
missing_org_units:
summary: Missing organizational units
value:
detail: Organizational units are required
'422':
description: Unprocessable Entity - Invalid organizational unit
content:
application/json:
examples:
invalid_organizational_unit:
summary: Invalid organizational unit
value:
detail:
error: Invalid organizational_unit
message: The organizational_unit 'ABC123' does not exist or you do not have permission to use it.
'503':
description: Service Unavailable
content:
application/json:
examples:
creation_error:
summary: Shipment creation failed
value:
detail: An error occurred creating the shipment
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
/v1/shipments/{shipment_id}:
get:
tags:
- Shipments
summary: Get Shipment
description: Get a shipment by ID.
operationId: get_shipment_by_id_shipments__shipment_id__get
parameters:
- name: shipment_id
in: path
required: true
schema:
type: string
format: uuid
title: Shipment Id
responses:
'200':
description: Shipment details retrieved successfully
content:
application/json:
schema:
title: Response Get Shipment By Id Shipments Shipment Id Get
$ref: '#/components/schemas/ShipmentDetailResponse'
nullable: true
examples:
electronics_shipment:
summary: Electronics shipment in transit
description: Phone components shipment from China to USA
value:
shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
shipment_name: Smartphone Components - Q4 2024
organization: ACME_CORP
organizational_unit:
- Electronics Division
- Mobile Devices
folder: electronics/smartphones
origin: Shenzhen, China
destination: Cupertino, CA, USA
departure_date: '2024-03-15T08:00:00Z'
arrival_date: '2024-03-25T14:30:00Z'
status: In Transit
active: true
detained_shipment:
summary: Detained medical shipment
description: Medical equipment shipment detained during customs inspection
value:
shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d480
shipment_name: Medical Equipment - Emergency Supply
organization: ACME_CORP
organizational_unit:
- Healthcare Division
detention_id: DET-2024-0315-001
folder: healthcare/medical_equipment
origin: Frankfurt, Germany
destination: New York, NY, USA
departure_date: '2024-03-10T10:00:00Z'
status: Detained
active: true
completed_automotive:
summary: Completed automotive shipment
description: Electric vehicle battery modules successfully delivered
value:
shipment_id: f47ac10b-58cc-4372-a567-0e02b2c3d481
shipment_name: EV Battery Modules - Shanghai to Fremont
organization: ACME_CORP
organizational_unit:
- Automotive Division
- EV Components
folder: automotive/ev/battery_modules
origin: Shanghai, China
destination: Fremont, CA, USA
departure_date: '2024-02-20T06:00:00Z'
arrival_date: '2024-03-05T11:45:00Z'
status: Complete
active: true
'400':
description: Bad request - invalid parameters
content:
application/json:
examples:
invalid_request:
summary: User lacks organizational units or invalid ID
value:
detail: User does not have any organizational units or shipment ID is invalid
'404':
description: Shipment not found
content:
application/json:
examples:
not_found:
summary: Shipment does not exist
value:
detail: Shipment not found
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Shipments
summary: Update Shipment
description: Updates an existing shipment. The shipment ID is specified in the URL path. Supports multiple organizational units per shipment for flexible organization structure management.
operationId: update_shipment_shipments__shipment_id__put
parameters:
- name: shipment_id
in: path
required: true
schema:
type: string
format: uuid
title: Shipment Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShipmentRequest'
examples:
update_electronics_shipment:
summary: Update Electronics Shipment
description: Update vehicle battery shipment with new arrival date
value:
shipment_name: 2024-Model3-Batteries-Updated
origin: Shanghai, China
destination: Fremont, CA, USA
departure_date: '2024-02-20T10:00:00Z'
arrival_date: '2024-03-12T16:45:00Z'
status: In Transit
active: true
organizational_units:
- automotive
- batteries
update_medical_shipment:
summary: Update Medical Shipment Status
description: Update medical supplies shipment status to Complete
value:
shipment_name: 2024-PPE-Emergency
origin: Hamburg, Germany
destination: New York, NY, USA
departure_date: '2024-03-05T06:00:00Z'
arrival_date: '2024-03-18T14:30:00Z'
status: Complete
active: true
organizational_units:
- medical
- emergency
minimal_update:
summary: Minimal Update Fields
description: Update with only required fields
value:
shipment_name: Updated-Shipment-2024
status: In Transit
organizational_units:
- default
responses:
'200':
description: Shipment updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentDetailResponse'
examples:
updated_electronics_shipment:
summary: Updated Electronics Shipment
description: Vehicle battery shipment updated with new arrival date
value:
shipment_id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
shipment_name: 2024-Model3-Batteries-Updated
organization: acme-motors
organizational_unit:
- automotive
- batteries
folder: 2024-Model3-Batteries
origin: Shanghai, China
destination: Fremont, CA, USA
departure_date: '2024-02-20T10:00:00Z'
arrival_date: '2024-03-12T16:45:00Z'
status: In Transit
active: true
updated_medical_shipment:
summary: Updated Medical Shipment
description: Medical supplies shipment status updated to Complete
value:
shipment_id: 550e8400-e29b-41d4-a716-446655440000
shipment_name: 2024-PPE-Emergency
organization: medical-corp
organizational_unit:
- medical
- emergency
folder: 2024-PPE-Emergency
origin: Hamburg, Germany
destination: New York, NY, USA
departure_date: '2024-03-05T06:00:00Z'
arrival_date: '2024-03-18T14:30:00Z'
status: Complete
active: true
'400':
description: Bad Request
content:
application/json:
examples:
invalid_org_units:
summary: Invalid organizational units
value:
detail: User does not have access to the specified organizational units
missing_org_units:
summary: Missing organizational units
value:
detail: Organizational units are required
'404':
description: Not Found
content:
application/json:
examples:
shipment_not_found:
summary: Shipment not found
value:
detail: Shipment not found
'503':
description: Service Unavailable
content:
application/json:
examples:
update_error:
summary: Shipment update failed
value:
detail: An error occurred updating the shipment
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/shipment/{shipment_id}/sirs:
get:
tags:
- Shipments
summary: Get supplier information requests
description: Get shipment supplier information requests
operationId: get_shipment_sirs_shipment__shipment_id__sirs_get
parameters:
- name: shipment_id
in: path
required: true
schema:
type: string
format: uuid
title: Shipment Id
- name: supplier_name
in: query
required: false
schema:
default: []
title: Supplier Name
type: array
items:
type: string
nullable: true
- name: supplier_jurisdiction
in: query
required: false
schema:
default: []
title: Supplier Jurisdiction
type: array
items:
type: string
nullable: true
- name: tradeverifyd_score
in: query
required: false
schema:
default: []
title: Tradeverifyd Score
type: array
items:
type: string
nullable: true
- name: status
in: query
required: false
schema:
default: []
title: Status
type: array
items:
type: string
nullable: true
- name: page
in: query
required: false
schema:
default: 1
title: Page
type: integer
nullable: true
- name: page_size
in: query
required: false
schema:
default: 25
title: Page Size
type: integer
nullable: true
- name: sorting
in: query
required: false
schema:
default: ''
title: Sorting
type: string
nullable: true
responses:
'200':
description: List of supplier information requests for the shipment
content:
application/json:
schema:
$ref: '#/components/schemas/SupplierInformationRequestListing'
examples:
multiple_sirs:
summary: Multiple SIRs with various statuses
description: Comprehensive list of supplier information requests with different risk scores and statuses
value:
requests:
- sir_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
supplier_name: ACME Corp
supplier_jurisdiction: TW
status: Documents Received
tradeverifyd_score: 572.5
- sir_id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
supplier_name: Electric Company
supplier_jurisdiction: KR
status: Documents Requested
tradeverifyd_score: 565.0
- sir_id: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
supplier_name: Manufacturing Group
supplier_jurisdiction: TW
status: Not Contacted
tradeverifyd_score: 558.3
- sir_id: 6ba7b812-9dad-11d1-80b4-00c04fd430c8
supplier_name: Wonka Industries
supplier_jurisdiction: KR
status: Eliminated
tradeverifyd_score: 545.2
pagination:
current_page: 1
page_size: 20
total_pages: 1
total_records: 4
sorting:
- supplier_name:asc
filters:
supplier_name: []
supplier_jurisdiction: []
status: []
tradeverifyd_score: []
filtered_by_status:
summary: SIRs filtered by status
description: Only showing SIRs with 'Documents Requested' status
value:
requests:
- sir_id: 550e8400-e29b-41d4-a716-446655440000
supplier_name: ACME Corp.
supplier_jurisdiction: CN
status: Documents Requested
tradeverifyd_score: 578.9
- sir_id: 550e8400-e29b-41d4-a716-446655440001
supplier_name: Technology Ltd.
supplier_jurisdiction: CN
status: Documents Requested
tradeverifyd_score: 582.1
pagination:
current_page: 1
page_size: 20
total_pages: 1
total_records: 2
sorting:
- tradeverifyd_score:desc
filters:
supplier_name: []
supplier_jurisdiction: []
status:
- Documents Requested
tradeverifyd_score: []
empty_results:
summary: No SIRs found
description: Empty result when no supplier information requests exist for the shipment
value:
requests: []
pagination:
current_page: 1
page_size: 20
total_pages: 0
total_records: 0
sorting: []
filters:
supplier_name: []
supplier_jurisdiction: []
status: []
tradeverifyd_score: []
'400':
description: Bad Request
content:
application/json:
examples:
no_org_units:
summary: No organizational units
value:
detail: User does not have any organizational units
invalid_paging:
summary: Invalid paging parameters
value:
detail: Invalid Paging Parameters
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/shipment/sirs/{sir_id}:
get:
tags:
- Shipments
summary: Get supplier information request
description: Get a shipment SIR by ID
operationId: get_shipment_sir_shipment_sirs__sir_id__get
parameters:
- name: sir_id
in: path
required: true
schema:
type: string
format: uuid
title: Sir Id
responses:
'200':
description: Detailed supplier information request
content:
application/json:
schema:
title: Response Get Shipment Sir Shipment Sirs Sir Id Get
$ref: '#/components/schemas/SupplierInformationRequestDetailResponse'
nullable: true
examples:
complete_sir:
summary: Complete SIR with all details
description: Fully populated supplier information request with parent company and reports
value:
sir_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
shipment_id: 123e4567-e89b-12d3-a456-426614174000
supplier_name: ACME CORP.
supplier_jurisdiction: US
supplier_parent_name: Wile E. Coyote Industries
supplier_parent_jurisdiction: TW
supplier_domain: acme.com
supplier_address: No. 1, Main Street Fairfield, New Jersey
status: Documents Received
tradeverifyd_score: 572.5
supplier_hs_codes: 8471,8473,8517,8542
related_parts: Cellphone displays, circuit boards, battery modules
product: Consumer Electronics Components
timeframe_start: '2024-01-01'
timeframe_stop: '2024-12-31'
reports:
- TASA_2024_Q1_ACME
- CPR_2024_ACME
entity_id: 507f1f77bcf86
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tradeverifyd/refs/heads/main/openapi/tradeverifyd-shipments-api-openapi.yml