Version: Next

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.

info

To get the most from the API, we recommend briefly reading the FAQ to understand the concepts behind the data, especially clustering.

Company Search

/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.

tip

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

Request to search for companies by name.
curl -X 'GET' 'http://<api_url>/companies/?name=boeing' -H 'accept: application/json'

Response
{
  "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

/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 (parents and subsidiaries)

/companies/{vid}/cluster_suppliers/

/companies/{vid}/customer_customers/

Use these endpoints to get a list of a company's suppliers or customers, ordered by the confidence of the relationship taking into account relationships of both parent and subsidiary companies in the cluster.

Notable fields in the response:

Field	Description
`count`	The number of suppliers or customers attached to the cluster.
`confidence_score`	The confidence score our AI and algorithms have assigned to this relationship.
`cluster_edge_id`	The unique identifer for the cluster relationship.
`edge_ids`	A list of the edge ids for the parent and subsidiaries in the cluster.

A simple example

This example fetches suppliers for Boeing, including any suppliers found within the Boeing cluster of subsidiaries given:

a confidence score of 0.8 or higher
supported by evidence later than 1st January 2019.

Request to get a list of suppliers for a company including any subsidiaries.
curl -X 'GET' \
  'http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/cluster_suppliers/?confidence_score=0.8&date=2019-01-01' \
  -H 'accept: application/json'

Response
{
  "count": 369,
  "next": "http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/cluster_suppliers/?confidence_score=0.8&date=2019-01-01&limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "cluster_edge_id": "oracle-boeing-supply",
      "from_parent_vid_id": "oraclecorp-27e324b2-6fb8-4161-90d3-167c8bc4c91d",
      "from_cid_id": "oracle",
      "to_parent_vid_id": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
      "to_cid_id": "boeing",
      "confidence_score": 1,
      "edge_ids": [
        "oraclecorp-27e324b2-6fb8-4161-90d3-167c8bc4c91d-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply"
      ]
    },
    {
      "cluster_edge_id": "libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce-boeing-supply",
      "from_parent_vid_id": "libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce",
      "from_cid_id": null,
      "to_parent_vid_id": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
      "to_cid_id": "boeing",
      "confidence_score": 1,
      "edge_ids": [
        "libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply"
      ]
    },
  ...
  ]
}

Company Suppliers & Customers

/companies/{vid}/suppliers/

/companies/{vid}/customers/

tip

These endpoints return relationships directly connected to the vid. We recommend using /{vid}/cluster_suppliers/ and /{vid}/cluster_customers/ to get a list of suppliers and customers to maximise the number of relationships returned.

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.

Notable fields in the response:

Field	Description
`count`	The number of suppliers or customers attached to the vid.
`confidence_score`	The confidence score our AI and algorithms have assigned to this relationship.
`edge_id`	The unique identifer for the relationship (also known as an edge).
`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.

Request to get a list of suppliers for a company.
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'

Response
{
  "count": 317,
  "next": "http://localhost:8000/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/suppliers/?confidence_score=0.8&date=2019-01-01&limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "edge_id": "flirsystems-7da1e111-2f91-45bf-8505-d68809172865-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply",
      "confidence_score": 1,
      "supplier": {...},
      "evidences": [...]
    },
    {
      "edge_id": "bridgestonecorp-56bf30a9-d172-4856-a86f-1b288105d662-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply",
      "confidence_score": 1,
      "supplier": {...},
      "evidences": [...]
    },
    ...
   ]
}      

Relationship (aka edge) Profile Lookup

/edges/{edge_id}/

Use this endpoint to get information about a specific relationship using the edge_id. The response includes the latest date found supporting the relationship, the confidence score, and a list of evidence items that support the relationship.

Cluster Profile Lookup

/clusters/{cid}/

Use this endpoint to find the record for a cluster, which includes the cid and the nominated_vid for a cluster. The nominated_vid is the company that we have chosen to represent the cluster in our database.

Cluster Contents

/clusters/{cid}/contents/

This endpoint will return the subsidiaries assigned to this cluster.

Cluster Relationship (aka cluster edge) Profile Lookup

/cluster_edges/{cluster_edge_id}/

Use this endpoint to get information about a specific cluster relationship using the cluster_edge_id. Like edges the response includes the latest date found supporting the relationshipa and the confidence score for the relationship. The response also includes a list of the edge_ids for the relationships attached to the parent and subsidiaries in the cluster.

Quickstart Examples

Company Search​

A simple example​

Company Profile Lookup​

Company Suppliers & Customers (parents and subsidiaries)​

A simple example​

Company Suppliers & Customers​

A simple example​

Relationship (aka edge) Profile Lookup​

Cluster Profile Lookup​

Cluster Contents​

Cluster Relationship (aka cluster edge) Profile Lookup​

Company Search

A simple example

Company Profile Lookup

Company Suppliers & Customers (parents and subsidiaries)

A simple example

Company Suppliers & Customers

A simple example

Relationship (aka edge) Profile Lookup

Cluster Profile Lookup

Cluster Contents

Cluster Relationship (aka cluster edge) Profile Lookup