Accurately Identifying Companies for B2B Orders using Two's Company API

Introduction

This guide details how to effectively use Two's Company API to find businesses, gather their verified information, and use this data to accurately populate buyer details when creating B2B orders. Using the Company API is crucial for precise buyer identification, which underpins Two's credit assessment, fraud prevention, and ensures smooth order processing.

While integrating the Company API is optional, it is highly recommended for reliably identifying the legal national_identifier of your buyers' companies. If you choose to omit the Company API, you must have an alternative, robust method for this identification. Existing KYC/KYB processes might provide these details, but submitting an invalid national identifier in an order request will cause the API call to fail. To prevent such issues and ensure data accuracy, we strongly advise using Two's Company API.

The process involves three key stages:

Stage 1: Discovering Companies: Learn how to search for companies using various criteria.
Stage 2: Retrieving Comprehensive Company Details: Understand how to fetch the full, verified profile of a specific company.
Stage 3: Populating Buyer Information for Order Creation: See how to use the retrieved data to correctly construct the buyer.company, billing_address, shipping_address, buyer.representative, and buyer_vat_number for your POST v1/order requests.

Stage 1: Discovering Companies – The Search

The first step is to find the company you intend to transact with. The Company API provides a powerful search endpoint for this purpose.

Using the `GET /companies/v2/company` Endpoint

To search for companies, you'll use the GET /companies/v2/company endpoint. This allows you to query Two's extensive company database.

Key Request Parameters:

q (string, required): The search term, typically the company name or a significant part of it. For effective results, provide at least 3 characters.
country (string, required): The two-letter ISO 3166-1 alpha-2 country code where the company is registered (e.g., "GB" for Great Britain, "US" for the United States, "SE" for Sweden).
limit (integer, optional): The maximum number of results to return. Defaults to a standard value if not specified.
offset (integer, optional): The number of results to skip, used for pagination.

Understanding the Search Response:

The API will return a list of company matches in the items array. Each company object in the list will typically include:

name: The official name of the company.
company_type: Type of organization the company operates as.
lookup_id: A unique identifier assigned by Two. This ID is essential for fetching the full details of the company in Stage 2.
national_identifier: An object containing the company's official registration number (id) and its country of registration.
country: The company's operational country (e.g., "GB").

Action: From the list of search results, identify the correct company. Note its lookup_id as you will need it to retrieve the full company details in the next stage.

This action, for example, in a typical e-commerce or checkout flow integration is driven by the buyer. The buyer is presented with an input field embedded with the Two Company API. They initiate a search for their company, and the API responds with an array of matching companies. This response can then be presented as a dropdown list from which the buyer can select their intended company.

An example implementation of a buyer-driven company search and dropdown selection can be found in our Company API search demo.

Stage 2: Retrieving Comprehensive Company Details

Once you have the lookup_id for the desired company (obtained in Stage 1), you can fetch its complete profile. The lookup_id is returned in the response of the GET /companies/v2/company call, and each item (company) returned in the array will have its own unique lookup_id. This response field can be found in the schema here.

Using the `GET /companies/v2/company/company_id` Endpoint

To get detailed information for a specific company, use the GET /companies/v2/company/company_id endpoint. The company_id in the path is the lookup_id obtained from the search results in Stage 1.

Understanding the Detailed Response (Get Company):

This endpoint returns a comprehensive object containing detailed information about the company. Key fields relevant for order creation, based on the company-api.yaml specification, include:

name: Official legal name of the company.
national_identifier: An object containing the company's primary official registration number (id) and its type (e.g., NO_BRREG, GB_CRN). The id is typically used as the organization number.
country: The company's country of registration (ISO 3166-1 alpha-2). This is crucial for the buyer.company.country_prefix field in order creation.
company_type: The general type of the company, an enum which can be SOLE_TRADER, GOVERNMENT, or UNDEFINED.
identifiers: An array of additional company identifiers. Each object in the array has an id and type.
addresses: An array of address objects associated with the company. You would typically look for an address with type: BUSINESS_ADDRESS for the official registered address. Each address object can include:
- type: The type of address (e.g., BUSINESS_ADDRESS, POSTAL_ADDRESS).
- street_address: Street name and number.
- postal_code: Postal or ZIP code.
- city: City or locality.
- region: State/Region/Province, if applicable.
- country: Two-letter ISO 3166-1 alpha-2 country code.
canonical_id: A unique canonical ID for the company, which can be used across Two's APIs.

Important Considerations:

The detailed information from the Get Company response is what you'll use to accurately define the buyer and associated details when creating an order.
This data can also be valuable if you're using Two's Trade Account API service for customer onboarding when creating a merchant_customer.
The address returned (typically BUSINESS_ADDRESS) is the official registered address of the company. When placing orders, it is required that the billing_address field in the order request accurately reflects this registered legal address. You can rely on the Company API's returned address to populate this, or use your internal records if you have verified them.

Stage 3: Constructing Buyer Information for Orders

With detailed company information from Stage 2, you can now construct the necessary data for your POST v1/order request. Accurate population of these fields is vital for Two's credit assessment, fraud prevention, and correct invoicing.

The key information to prepare for the Order API includes:

buyer.company: Core details of the business making the purchase.
billing_address: The official registered address of the company for invoicing.
shipping_address: The address for delivering goods or services.
buyer.representative: Information about the individual acting on behalf of the company.
buyer_vat_number: The company's VAT identification number, if applicable.

Mapping Company API Data to Order API Fields:

Here’s how data from the Company API (GET /companies/v2/company/company_id response) maps to the Order API request fields:

1. buyer.company Object: This object contains the core details of the purchasing company.

`buyer.company` Field (Order API)	Company API Source Field	Notes (Order API Spec)
`country_prefix`	`country`	Required, ISO 3166-1 alpha-2
`organization_number`	`national_identifier.id`	Required
`company_name`	`name`	Optional (but highly recommended)
`company_type`	`company_type`	Optional
`website`	-	Optional (Not directly available from Company API's. Can be added if known from other sources.)

2. billing_address Object: The billing address must be the company's official registered address.

Source: Use the address object from the addresses array (obtained in Stage 2) where type is BUSINESS_ADDRESS.
Map the fields like street_address, postal_code, city, region, and country from the Company API's address object to the corresponding fields in the Order API's billing_address object. Refer to the Create Order API specification for the exact structure of the billing_address object.

3. shipping_address Object: The shipping address may differ from the billing address.

Source: The Company API provides registered addresses, which are ideal for billing. The shipping_address is typically provided by the buyer during the checkout process, as it reflects their desired delivery location.
If the shipping address is the same as the billing address, you can reuse the BUSINESS_ADDRESS data. Otherwise, collect it from the buyer.

Importance of Accuracy: Providing complete and accurate company, address, and representative information allows Two to perform reliable credit checks and ensures that invoices are correctly addressed and processed. Using the Company API as the primary source for company and billing address data significantly improves data quality and reduces the risk of errors.

Conclusion

Two's Company API is an indispensable tool for accurately identifying businesses and gathering the verified details essential for B2B order creation. By following the three stages outlined in this guide—discovering companies, retrieving their comprehensive details, and meticulously mapping this information to your order requests—you can significantly enhance the reliability of your integration. This leads to more accurate credit assessments, reduced risk of fraud, correct invoicing, and ultimately, smoother and more trustworthy B2B transactions with Two.