Operations involving entities. Entities encompass a range of organizations and individuals, primarily focusing on companies. This section provides functionalities to manage and interact with information about various entities, including their details, activities, and roles in the supply chain.
openapi: 3.1.0
info:
title: Tradeverifyd Documents Entity 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: Entity
description: Operations involving entities. Entities encompass a range of organizations and individuals, primarily focusing on companies. This section provides functionalities to manage and interact with information about various entities, including their details, activities, and roles in the supply chain.
paths:
/v1/search/entities:
get:
tags:
- Entity
summary: Entity Search
description: Search for Entities that match the provided search parameters.
operationId: search_entities_search_entities_get
parameters:
- name: name
in: query
required: true
schema:
type: string
description: Entity name.
title: Name
description: Entity name.
- name: address
in: query
required: false
schema:
description: Entity address.
title: Address
type: string
nullable: true
description: Entity address.
- name: jurisdiction
in: query
required: false
schema:
description: Two-letter ISO country code the entity should be associated with.
title: Jurisdiction
type: string
minLength: 2
maxLength: 2
nullable: true
description: Two-letter ISO country code the entity should be associated with.
- name: size
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: The maximum number of results to return. Must be between 1 and 100, inclusive.
default: 10
title: Size
description: The maximum number of results to return. Must be between 1 and 100, inclusive.
- name: flagged_only
in: query
required: false
schema:
type: boolean
description: If 'true', results will be limited to Entities currently affected by 1 or more Flags.
default: false
title: Flagged Only
description: If 'true', results will be limited to Entities currently affected by 1 or more Flags.
responses:
'200':
description: Entities matching search criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntitySearchResult'
title: Response Search Entities Search Entities Get
examples:
entity_name_search:
summary: Search by entity name
description: Find entities matching a specific company name
value:
- id: 507f1f77bcf86cd799439011
name: Global Manufacturing Corp
aliases:
- GMC
jurisdiction: US
addresses:
- 123 Industrial Blvd, Detroit, MI 48201, USA
- 456 Factory St, Cleveland, OH 44113, USA
flagged: true
description: Large-scale manufacturing company specializing in automotive components
primary_role: manufacturer
url: https://globalmanufacturingcorp.example
monitor: true
references:
flags:
total: 2
relationships:
total: 15
from_relationships:
count: 8
to_relationships:
count: 7
risk_events:
total: 1
external_ids:
- id: US-12345678-901
type: duns
source: dun_bradstreet
- id: '98765432109876543210'
type: lei
source: gleif
modified_date: '2024-10-15T14:30:00Z'
- id: 507f1f77bcf86cd799439012
name: Global Manufacturing Example Solutions
aliases:
- GMES
jurisdiction: CA
addresses:
- 789 Commerce Way, Toronto, ON M5V 3B6, Canada
flagged: false
description: Manufacturing solutions provider
primary_role: supplier
references:
flags:
total: 0
relationships:
total: 3
risk_events:
total: 0
count_inferred_relationships:
depth: 3
value: 3
flagged_count: 0
last_updated: '2025-10-08T19:34:19.447000Z'
modified_date: '2024-10-20T09:15:00Z'
hs_codes:
incoming:
- '52'
- '5214'
- '521462'
outgoing:
- '81'
- '8105'
- '810507'
flagged_entities_only:
summary: Search flagged entities only
description: Find only entities with active compliance flags
value:
- id: 507f1f77bcf86cd799439013
name: Risky Suppliers Ltd
aliases:
- Risky Ltd.
jurisdiction: CN
addresses:
- Room 1001, Building A, Shenzhen, Guangdong, China
flagged: true
description: Electronics components supplier with compliance concerns
primary_role: supplier
monitor: true
references:
flags:
total: 3
relationships:
total: 12
risk_events:
total: 2
modified_date: '2024-10-18T16:45:00Z'
jurisdiction_search:
summary: Search by jurisdiction
description: Find entities in a specific country (Germany)
value:
- id: 507f1f77bcf86cd799439014
name: Great German Engineering Co.
aliases:
- GEC
jurisdiction: DE
addresses:
- Industriestraße 42, 70565 Stuttgart, Germany
flagged: false
description: High-precision manufacturing and engineering services
primary_role: manufacturer
url: https://great-engineering-example.de
references:
flags:
total: 0
relationships:
total: 8
risk_events:
total: 0
external_ids:
- id: HRB123456
type: company_registration
source: german_trade_register
count_inferred_relationships:
depth: 3
value: 3
flagged_count: 1
last_updated: '2025-01-01T00:00:00Z'
modified_date: '2024-10-10T11:20:00Z'
hs_codes:
incoming: []
outgoing:
- '1050'
empty_results:
summary: No matching entities
description: Search that returns no results
value: []
'400':
description: Bad Request - Invalid search parameters
content:
application/json:
examples:
missing_search_criteria:
summary: Missing required search criteria
value:
detail: Either name or entity_id must be provided
invalid_jurisdiction:
summary: Invalid jurisdiction code
value:
detail: Jurisdiction must be a 2-letter ISO country code
invalid_size:
summary: Invalid size parameter
value:
detail: Size must be between 1 and 100
'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/resolve/entity:
get:
tags:
- Entity
summary: Entity Resolution
description: Resolve to the top-scoring Entity that matches the provided search parameters.
operationId: resolve_entity_resolve_entity_get
parameters:
- name: name
in: query
required: true
schema:
type: string
description: Entity name.
title: Name
description: Entity name.
- name: address
in: query
required: false
schema:
description: Entity address.
title: Address
type: string
nullable: true
description: Entity address.
- name: jurisdiction
in: query
required: false
schema:
description: Two-letter ISO country code the entity should be associated with.
title: Jurisdiction
type: string
minLength: 2
maxLength: 2
nullable: true
description: Two-letter ISO country code the entity should be associated with.
- name: flagged_only
in: query
required: false
schema:
type: boolean
description: If 'true', results will be limited to Entities currently affected by 1 or more Flags.
default: false
title: Flagged Only
description: If 'true', results will be limited to Entities currently affected by 1 or more Flags.
responses:
'200':
description: Best matching entity resolved from search criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntitySearchResult'
title: Response Resolve Entity Resolve Entity Get
examples:
perfect_name_match:
summary: Perfect entity name match
description: Exact match found for entity name with high confidence
value:
- id: 507f1f77bcf86cd799439015
name: Example Contoso Inc.
aliases:
- CONTOSO
- EX CONTOSO
jurisdiction: US
addresses:
- 123 Main Street, Anytown, State, 12345
flagged: false
description: Multinational technology company specializing in consumer electronics
primary_role: manufacturer
url: https://contoso.example
monitor: true
auto_research: true
references:
flags:
total: 0
relationships:
total: 247
from_relationships:
count: 156
to_relationships:
count: 91
risk_events:
total: 0
external_ids:
- id: '32019387069'
type: duns
source: dun_bradstreet
- id: HWUPKR0MPOU8FGXBT394
type: lei
source: gleif
- id: CONT
type: ticker
source: nasdaq
count_inferred_relationships:
depth: 3
value: 3
flagged_count: 0
last_updated: '2025-10-08T19:34:19.447000Z'
modified_date: '2024-10-22T08:30:00Z'
hs_codes:
incoming: []
outgoing:
- '68'
- '6802'
- '680221'
fuzzy_name_match:
summary: Fuzzy entity name match
description: Best match found despite slight name variations
value:
- id: 507f1f77bcf86cd799439016
name: Contoso Inc.
aliases:
- CONTOSO
jurisdiction: US
addresses:
- 123 Main Street, Anytown, State, 12345
flagged: false
description: Technology corporation developing software, services, and solutions
primary_role: manufacturer
url: https://contoso.example
monitor: true
references:
flags:
total: 0
relationships:
total: 189
risk_events:
total: 0
external_ids:
- id: 06-1232893
type: ein
source: irs
- id: CONT
type: ticker
source: nasdaq
modified_date: '2024-10-21T14:15:00Z'
jurisdiction_resolved:
summary: Resolution with jurisdiction filtering
description: Best match within specific jurisdiction constraint
value:
- id: 507f1f77bcf86cd799439017
name: ACME CORP
aliases:
- ACME
jurisdiction: US
addresses:
- 789 1st Street, Anytown, State, 12345
flagged: false
description: Multinational automotive manufacturer
primary_role: manufacturer
url: https://acme.example
monitor: true
references:
flags:
total: 0
relationships:
total: 412
from_relationships:
count: 298
to_relationships:
count: 114
risk_events:
total: 0
external_ids:
- id: US-7200001008846
type: corporate_number
source: us_corporate_number
- id: AC
type: ticker
source: nyse
modified_date: '2024-10-19T10:45:00Z'
flagged_entity_resolved:
summary: Flagged entity resolution
description: Best match for flagged entity with compliance issues
value:
- id: 507f1f77bcf86cd799439018
name: Sanctioned Trading LLC
aliases:
- Sanctioned Trading
jurisdiction: RU
addresses:
- 123 Red Square, Moscow, Russia
flagged: true
description: Trading company with active sanctions flags
primary_role: trader
monitor: true
auto_research: false
references:
flags:
total: 5
relationships:
total: 23
risk_events:
total: 3
external_ids:
- id: RU-1027700132195
type: ogrn
source: russian_business_register
modified_date: '2024-10-23T12:00:00Z'
no_resolution:
summary: No entity resolved
description: No suitable match found for search criteria
value: []
'422':
description: Invalid resolution parameters.
content:
application/json:
examples:
invalid_jurisdiction:
summary: Invalid jurisdiction code
description: Provided jurisdiction has too many characters
value:
detail:
- type: string_too_long
loc:
- query
- jurisdiction
msg: String should have at most 2 characters
input: USA
ctx:
max_length: 2
'500':
description: Internal server error - contact support
content:
application/json:
examples:
internal_error:
summary: Internal server error
value:
detail: Internal server error
/v1/entities/by-flag-type/{flag_type_id}:
get:
tags:
- Entity
summary: Get Entities by Flag Type
description: 'Get entities that have flags of a specific flag type. To view possible flag types, use
the Get Flags Types endpoint `/flags/types`.
This endpoint allows customers to query entities based on specific compliance flags.
Results are filtered by organization, meaning only entities with flags that are either
public or belong to the user''s organization will be returned.
The response includes a list of entities that have a flag of the specified type, including information
on entity details, Tradeverifyd scores, and flag information.
Because the response can be large, entities are returned across multiple pages of the response.
The response includes information on the maximum number of pages.
Use the `limit` parameter to specify how many results should be returned in one page.
Use the `page` parameter to select a page number.'
operationId: get_entities_by_flag_type_entities_by_flag_type__flag_type_id__get
parameters:
- name: flag_type_id
in: path
required: true
schema:
type: string
description: ObjectId of the flag type to filter entities by
title: Flag Type Id
description: ObjectId of the flag type to filter entities by
- name: page
in: query
required: false
schema:
type: integer
description: Page number for pagination
default: 1
title: Page
description: Page number for pagination
- name: limit
in: query
required: false
schema:
type: integer
description: Number of entities per page
default: 50
title: Limit
description: Number of entities per page
responses:
'200':
description: Entities with the specified flag type
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Entities By Flag Type Entities By Flag Type Flag Type Id Get
examples:
ndaa_1260h_entities:
summary: NDAA 1260H flagged entities
description: Entities flagged under Section 1260H of the National Defense Authorization Act
value:
entities:
- id: 67ca2eb28f1f60aa37278f33
name: EXAMPLE CONTOSO INC.
jurisdiction: US
type: Company
status: Active
addresses:
- 123 Main Street, Anytown, State, 12345
flags:
- id: 6808e96feb30f71f4da957c8
created_at: '2025-03-15T00:11:31.376Z'
type: 67db2af315fadaf237af6a0e
flag_type: Sanctions & Restricted Entities Risk
flag_subtype: 1260H Entities
flag_polarity: -1
description: A flag that describes an staged_flag on the OpenSanctions default list.
sources:
- url: https://www.defense.gov/News/Releases/Release/Article/4023145/
aliases:
- CONTOSO
- EX CONTOSO
pagination:
page: 1
limit: 50
total_entities: 127
total_pages: 3
has_next: true
has_previous: false
filter_summary:
flag_type_id: 67db2af315fadaf237af6a0e
flag_type: Sanctions & Restricted Entities Risk
flag_subtype: 1260H Entities
flag_polarity: -1
'400':
description: Bad Request - Invalid parameters
content:
application/json:
examples:
invalid_object_id:
summary: Invalid flag type ID format
value:
detail: flag_type_id must be a valid ObjectId
invalid_pagination:
summary: Invalid pagination parameters
value:
detail: page must be >= 1, limit must be >= 1 and <= 500
'404':
description: Flag type not found
content:
application/json:
examples:
flag_type_not_found:
summary: Flag type does not exist
value:
detail: Flag type 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'
/v1/entities/{entity_id}:
get:
tags:
- Entity
summary: Get Entity
description: Retrieve a single Entity by its Id
operationId: get_entity_entities__entity_id__get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
title: Entity Id
responses:
'200':
description: Successful entity match.
content:
application/json:
schema:
$ref: '#/components/schemas/GetEntityResponse'
examples:
entity_id_search:
summary: Search by entity_id
description: Find a single entity by entity_id.
value:
id: 507f1f77bcf86cd799439015
name: Example Contoso Inc.
description: Large-scale manufacturing company specializing in automotive components
primary_role: manufacturer
aliases:
- Contoso
- EX CONTOSO
url: https://globalmanufacturingcorp.example
jurisdiction: US
addresses:
- 123 Main Street, Anytown, State, 12345
monitor: false
created_at: '1970-01-01T00:00:00.000Z'
modified: '1970-01-01T00:00:00.000Z'
region: State
affiliated_jurisdiction: CA
tradeverifyd_score: 550
references:
flags:
total: 2
relationships:
total: 15
from_relationships:
count: 8
to_relationships:
count: 7
risk_events:
total: 1
count_inferred_relationships:
depth: 2
value: 2
last_updated: '1970-01-01T00:00:00.000Z'
'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/entities/{entity_id}/risk_events:
get:
tags:
- Entity
summary: Get Entity Risk Events
description: Get Risk Events affecting an Entity.
operationId: get_entity_risk_events_entities__entity_id__risk_events_get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
title: Entity Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RiskEvent'
title: Response Get Entity Risk Events Entities Entity Id Risk Events Get
'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/entities/{entity_id}/verification:
get:
tags:
- Entity
summary: Get Entity Verification by entity id
description: 'Retrieves the Tradeverifyd Supplier Assessment (TSA) details for a given entity. Returns the current
supplier assessment and compliance information recorded for the specified entity.
Note: To generate a Tradeverifyd Advanced Supplier Assessment (TASA), use the POST /reports endpoint.'
operationId: get_entity_verification_details_entities__entity_id__verification_get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
description: Id of the Entity to use as the starting node for graph retrieval.
title: Entity Id
description: Id of the Entity to use as the starting node for graph retrieval.
- name: hs_code
in: query
required: false
schema:
description: 'Optional HS code (2, 4, or 6-digit) to filter the supplier graph used for assessment. When provided, only supplier relationships (IS_SUPPLIER_OF edges) that match the HS code are considered when analyzing the entity''s supply chain. This filters the graph to show suppliers of specific products. Less specific codes (e.g., ''52'') match more specific codes (e.g., ''5201'', ''520100''). Note: Supplier jurisdiction filtering will be added in future updates.'
title: Hs Code
type: string
nullable: true
description: 'Optional HS code (2, 4, or 6-digit) to filter the supplier graph used for assessment. When provided, only supplier relationships (IS_SUPPLIER_OF edges) that match the HS code are considered when analyzing the entity''s supply chain. This filters the graph to show suppliers of specific products. Less specific codes (e.g., ''52'') match more specific codes (e.g., ''5201'', ''520100''). Note: Supplier jurisdiction filtering will be added in future updates.'
responses:
'200':
description: Successful entity verification retrieval.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityVerificationDetails'
examples:
verification_id_search:
summary: Get entity verification details by entity_id.
description: Find an entity's verification details by entity_id.
value:
id: 507f1f77bcf86cd799439015
name: Example Contoso Inc.
jurisdiction: US
addresses:
- 123 Main Street, Anytown, State, 12345
text_summary: One company in this supply chain has been flagged for compliance issues.
problematic_entities:
- id: 507f1f77bcf86cd799439017
name: ACME CORP.
flags:
- sources:
- https://www.dhs.gov/uflpa-entity-list
type: Human Rights Violation Risk
subtype: Forced Labor Risk
flag_polarity: -1
addresses:
- address: 789 1st Street, Anytown, State, 12345
problematic: true
problem_region: AK
jurisdiction: US
depth: 3
tvpra_risks:
- risk_type: forced_labor
suspect_hs_codes:
- '52'
has_excessive_addresses: false
tradeverifyd_score: 550
total_entity_ct: 1
identifiers:
- type: lei
source: https://lei-lookup.com/record/example
id: 1b070d5e-eb8d-41e6-9055-a26f8f638571
incoming_products:
- '52'
- '61'
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tradeverifyd/refs/heads/main/openapi/tradeverifyd-entity-api-openapi.yml