Quickstart Examples
This is a quickstart guide to our API. It will show you how to get started and how to use it to find information about companies and their supply chains.
Company Search
/v1/companies/
You can use this endpoint to search for companies by name, city, country, website or identifier. Use the limit (defaults to 10) and offset parameters to paginate through the results.
The default search options only search for parent companies of the clusters created and any company not in a cluster. To search for all companies in the database, use the include_subsidiaries=true parameter.
The response includes a number of important fields to help with matching:
| Field | Description |
|---|---|
search_similarity | If a name is provided in the input, this returns the trigram similarity to the record. |
count_suppliers | The number of suppliers in the database for the company. |
count_customers | The number of customers in the database for the company. |
cid_id | The identifier of the cluster the company belongs to. |
A simple example
curl -X 'GET' 'http://<api_url>/companies/?name=boeing' -H 'accept: application/json'
{
"next": "http://<api_url>/companies/?limit=10&name=boeing&offset=10",
"previous": null,
"results": [
{
"search_similarity": 0.7,
"vid": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
"cid_id": "boeing",
"name": "Boeing Co",
"domains": [
"boeing.com"
],
"websites": [
"https://www.boeing.com/"
],
"company_legal_name": "Boeing Co",
"description": "aerospace and defense manufacturer in the United States",
"count_supplier_evidence": 3094,
"count_customer_evidence": 5957,
"count_customers": 558,
"count_suppliers": 561,
...
}
...
]
}
Company Profile Lookup
/v1/companies/{vid}/
Use this endpoint to get information about a specific company. The company is identified by its vid - a unique identifier we assign to each company in our database. Use the company search endpoint to find the vid for a company.
Here is a list of the fields on the company profile and their descriptions:
| Field | Description |
|---|---|
vid | The unique identifier for the company. |
cid_id | The identifier of the cluster the company belongs to. |
name | The name of the company. Where possible this is the legal name. |
domains | A list of domains associated with the company. |
websites | A list of websites associated with the company. |
company_legal_name | The legal name of the company. |
description | A description of the company. |
count_supplier_evidence | The number of evidences in the database for the supply relationships. |
count_customer_evidence | The number of evidences in the database for the customer relationships. |
count_customers | The number of customers in the database for the company. |
count_suppliers | The number of suppliers in the database for the company. |
identifiers | A list of identifiers associated with the company. |
domiciled_country | ISO3166 long form of the country the company is domiciled in. |
incorporated_country | ISO3166 long form of the country the company is incorporated in. |
incorporation_date | Date and time of company incorporation. |
ipo_date | Date and time of company incorporation. |
is_active | Whether the company is active. |
is_freight_forwarder | Whether the company is a freight forwarder. |
is_public | Whether the company is publicly listed. |
hq_phone_number | Phone number of the headquarters. |
addresses | A list of addresses associated with the company. |
Company Suppliers & Customers
/v1/companies/{vid}/suppliers/
/v1/companies/{vid}/customers/
Use these endpoints to get a list of a company's suppliers or customers, ordered by the confidence of the relationship. Each item in the response list is a relationship terminating or originating at the vid company or the company cluster if grouped.
Notable fields in the response:
| Field | Description |
|---|---|
confidence_score | The confidence score our AI and algorithms have assigned to this relationship. |
edge_ids | The unique identifers of the edges underlying the suppliers or customers. |
evidences | A list of evidence items that support the relationship. |
A simple example
This example fetches suppliers for Boeing:
- with a confidence score of 0.8 or higher
- supported by evidence later than 1st January 2019.
curl -X 'GET' \
'http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/suppliers/?confidence_score=0.8&date=2019-01-01' \
-H 'accept: application/json'
{
"results": [
{
"supplier": {
"vid": "baesystemsplc-de467c3d-e1da-4849-8344-79cbdcefae94",
"name": "BAE Systems PLC",
"company_legal_name": "BAE Systems PLC",
"description": "defense, security and aerospace company",
"domains": [
"baesystems.com"
],
"country": "United Kingdom",
"count_supplier_evidence": 437,
"count_customer_evidence": 1958,
"count_customers": 206,
"count_suppliers": 209
},
"relationship": {
"confidence_score": 1,
"latest_relationship_date": "2023-07-17T00:00:00Z",
"relationship_type": "cluster_edge",
"relationship_id": "baesystemsplc-de467c3d-e1da-4849-8344-79cbdcefae94-boeing-supply",
"edge_ids": [
"baesystemsplc-de467c3d-e1da-4849-8344-79cbdcefae94-boeingaustralia-48005293-3f7e-41b7-a905-84bfb19e30fd-supply",
"baesystemsplc-de467c3d-e1da-4849-8344-79cbdcefae94-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply"
]
},
"evidences": {
"evidence_types": [
"text"
]
}
},
...
]
}
Relationship (aka edge) Profile Lookup
/v1/edges/{edge_id}/
Use this endpoint to get information about a specific relationship using the edge_id taken from the edge_ids field in the relationship subsection from the suppliers or customers endpoint. The response includes the latest date found supporting the relationship, the confidence score, and a list of evidence items that support the relationship.
{
"edge_id": "teijinltd-5faa81b8-958a-4cf3-a897-f2451be68ceb-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply",
"supplier_id": "teijinltd-5faa81b8-958a-4cf3-a897-f2451be68ceb",
"customer_id": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
"label": "supply",
"status_code": 4,
"latest_edge_date": "2023-01-09T00:00:00Z",
"latest_finalized_edge_date": "2021-07-21T00:00:00Z",
"last_modified_on": "2023-09-22T00:11:27.663000Z",
"confidence_score": 1,
"evidences": [
{
"id": "ce48d080686f8f9382431862ddccda72",
"date": "2016-06-08T00:00:00Z",
"type": "text",
"url": "https://www.eppm.com/materials/teijin-to-supply-tenax-carbon-fibre-thermoplastic-for-boeing/",
"domain": "eppm.com",
"status_id": 0,
"provided_by_customer": null,
"metadata": null,
"finalised_on": null,
"created_on": "2023-08-07T13:34:47.323000Z",
"last_modified_on": "2023-08-07T13:34:47.323000Z"
},
...
]
}