> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# International Products: API Quickstart

> Verify a non-US business in a few calls: search by name and address, or by filing number for a precise match.

## International Business Search: API Quickstart

This quickstart covers the **Business Verification** side of Baselayer International **Search** product, which returns corporate registration data for businesses in 76 supported jurisdictions. For the conceptual overview (and for international **Web Presence**), see [International Products: Basics](https://docs.baselayer.com/docs/baselayer-international-products.md).

> **Note**: International Business Search is **API-only** for now, and uses a separate route from the US Business Search (`/international/searches`, not `/searches`). The two are not interchangeable.

***

### Before you start

* You need a Baselayer API key. Requests are authenticated the same way as every other Baselayer endpoint. See [Authentication](https://docs.baselayer.com/docs/authentication.md).
* You can develop against the sandbox before going live. See [Sandbox vs. Production Environments](https://docs.baselayer.com/docs/sandbox-vs-production-environments.md).
* Every request must include an `iso2_country_code` (ISO 3166-1 alpha-2, e.g. `GB`, `DE`, `CA`). It must be one of the 76 supported countries listed in the [Basics guide](https://docs.baselayer.com/docs/baselayer-international-products.md).

***

### Step 1: Choose how you'll search

`POST /international/searches` accepts two ways to identify a business. Both require `iso2_country_code`.

| Mode | Provide |
| - | - |
| **Name + address** | `name` **and** `address` |
| **Registration number** | `filing_number`, optionally with `name` and/or `address` |

**Name + address is the standard approach, and all you need for the vast majority of searches**, treat it as your default.

The registration number is a good **optional** input to offer alongside it. In many countries, owners and finance staff know their company's registration number by heart, so letting them enter it is fast and familiar. When `filing_number` is provided, the registry is searched by that number first; a `name`, if also provided, is used as a fallback when no company matches the number. With a `filing_number`, `name` and `address` are each optional; without one, both are required.

> **Tip**: Label the registration-number field with the **local term** so users recognize it: for example, in Spain it's the **CIF**. See [Best Practices](https://docs.baselayer.com/docs/international-products-best-practices.md) for more.

***

### Step 2 (optional add-on): Offer a registration lookup

This step is entirely optional and not needed for a great result. If you find match rates in a particular market could be better, you can offer users a smoother path: look up candidates with `GET /international/registrations`, show them the list, and let them pick the right one. Then search using that result's `filing_number`.

```javascript Text theme={null}
GET /international/registrations?iso2_country_code=GB&name=Acme%20Ltd
```

Query parameters: `iso2_country_code`, `name`, and/or `filing_number`. The endpoint returns a **list of matching registrations** to choose from. Take the `filing_number` of the chosen result and use it in Step 3.

Think of this as a nice enhancement, not a requirement: a plain name + address search is a perfectly good one-step flow.

***

### Step 3: Create the search

**By name + address:**

```javascript Text theme={null}
POST /international/searches

{
    "name": "Acme Ltd",
    "address": "1 Parliament St, London SW1A 2JR, United Kingdom",
    "iso2_country_code": "GB"
}
```

**By filing number** (e.g. a `filing_number` chosen from Step 2):

```javascript Text theme={null}
POST /international/searches

{
    "filing_number": "01234567",
    "iso2_country_code": "GB"
}
```

**Optional fields** (either mode): `officer_names`, `website`, `phone_number`, `email`, `alternative_names`, and `reference_id` (your internal tracking ID).

**Enhanced Profile add-on:** to also return directors, ultimate beneficial owners, shareholders, and share capital where available, request the `Order.Enhanced` option. It is billed separately, and cost varies per country.

```javascript Text theme={null}
POST /international/searches

{
    "filing_number": "01234567",
    "iso2_country_code": "GB",
    "options": ["Order.Enhanced"]
}
```

***

### Step 4: Get the results

International Business Search is asynchronous. The `POST` returns immediately with an `id`; retrieve results when the search completes, via webhook (recommended) or polling.

```javascript Text theme={null}
GET /international/searches/{id}
GET /international/searches
```

**Webhooks:**

* `InternationalBusinessSearch.submitted`: accepted and processing
* `InternationalBusinessSearch.completed`: results are available
* `InternationalBusinessSearch.failed`: no associated business was found

See the [Webhooks at Baselayer](https://docs.baselayer.com/docs/webhooks-at-baselayer.md) to configure delivery.

***

### Step 5: Read the response

A completed search returns a `business` object. These fields are present across all countries:

* `name`: the official registered name
* `file_number`: the registration/filing number in the local registry
* `status`: normalized to `active`, `inactive`, or `unknown`
* `country`: the ISO2 country code of the registration

The response also tells you **how well your inputs matched** the company found at the registry, the same match signals the US Business Search returns:

* `business_name_match`: how closely your `name` matched: `EXACT`, `SIMILAR`, or `NO_MATCH` (identical to the US).
* `business_address_match`: how closely your `address` matched, at international granularity: `EXACT`, `CITY`, `REGION`, `COUNTRY`, or `NO_MATCH`.
* `filing_number_match`: a boolean specific to international search: `true` if the `filing_number` you supplied located the company at the registry, `false` if the search fell back to the name, and `null` if you didn't supply a filing number.

Any match field is `null` when the corresponding input wasn't provided. Use `business_name_match` and `business_address_match` for decisioning exactly as you do for US searches.

The response also includes **`watchlist_hits`**: the company, any `alternative_names` you sent, and its current officers and beneficial owners are screened against OFAC, CSL, FBI, Canadian sanctions and OIG (plus PEP when you order `Order.Pep`), following your [Account Settings](https://docs.baselayer.com/docs/account-settings.md). Each entry has `code`, `name`, `count` and `details`. A `count` of `0` means screened with no match; a list that's absent wasn't screened. A confirmed OFAC hit sets Risk to `0` / `F`.

International Business Search also returns **KYB and Risk ratings on the same scale** as the US product, with the same grade bands (A ≥ 90, B ≥ 80, C ≥ 60; only A and B count as `verified`), so you can apply your existing thresholds. The KYB score only counts the inputs you sent. See the [international scoring section](https://docs.baselayer.com/docs/baselayer-international-products.md#scores-and-ratings) and [Scores & Ratings](https://docs.baselayer.com/docs/baselayer-scores-ratings.md).

> **Important**: Data depth varies by country. Most countries return the core registration fields above; some return more. `status` is always normalized to `active` / `inactive` / `unknown`.

***

### End-to-End Flow Summary

That's a complete international business verification:

1. **Identify the business**: by name + address (the default), or by registration number where the user has it.
2. **Create the search**: `POST /international/searches` with `iso2_country_code`, optionally adding `Order.Enhanced` for ownership data.
3. **Receive results**: via the `InternationalBusinessSearch.completed` webhook, or by polling `GET /international/searches/{id}`.
4. **Decide**: read the `business` object and apply your existing KYB and Risk thresholds.

With this in place, you can verify businesses across 76 jurisdictions through the same request-and-webhook pattern you already use for US searches.

***

### Where to Go Next

* **[International Products: Best Practices](https://docs.baselayer.com/docs/international-products-best-practices.md)** — Offering and localizing the registration-number field, when to use Enhanced Profiles, what varies by country, and how to handle low match rates.
* **[International Products: Basics](https://docs.baselayer.com/docs/baselayer-international-products.md)** — The full overview: supported countries and international Web Presence.
* **[Scores & Ratings](https://docs.baselayer.com/docs/baselayer-scores-ratings.md)** — How KYB and Risk ratings are calculated and how to threshold on them.
* **[Webhooks](https://docs.baselayer.com/docs/webhooks-at-baselayer.md)** — Configuring delivery for `InternationalBusinessSearch` events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.