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

# Auto.Complete SDK

> Add a business typeahead to your own product with @baselayer-sdk/autocomplete, and run KYB on exactly the business that was picked.

This page is for developers adding Baselayer's business typeahead to their own forms. As someone types, they see matching businesses from official registry records and pick theirs. The pick gives you a `business_token`, and your KYB search runs on exactly that business, with no typos and no wrong-business matches.

Try it in the [live demo](https://sdk.baselayer.com/autocomplete/demo/) with your own API key. For how the product works, see [Auto.Complete](https://docs.baselayer.com/docs/auto-complete.md).

The SDK's own site is shown below, with the full guide, styling options and API reference. If the frame is too small, [open the SDK site](https://sdk.baselayer.com/autocomplete/) in its own tab.

[Auto.Complete SDK](https://sdk.baselayer.com/autocomplete/)

## What's in the package

| Import | What it is |
| - | - |
| `@baselayer-sdk/autocomplete` | The framework-free core: sessions, refresh, backoff, and handling for every refusal the API can return. |
| `@baselayer-sdk/autocomplete/react` | Hooks, and styled components you can restyle: `BusinessAutocomplete`, `PersonAutocomplete` and `AddressAutocomplete`. |
| `@baselayer-sdk/autocomplete/server` | The one endpoint your backend adds, so your API key never reaches a browser. |

The SDK finds a business three ways: by its name, by a person who holds a role at it, or by an address it is filed at. Whichever way, the pick is a business.

## Install

```bash theme={null}
npm install @baselayer-sdk/autocomplete
```

React 18 or 19 is optional. The core and the server helper need neither React nor a browser. The package needs Node 20 or later.

> [!NOTE]
>
> The SDK is pre-release (version 0.x). Until 1.0, a breaking change bumps the minor version, so pin the minor version you test with.

## How it fits together

1. When the field is used, the SDK asks your backend for a session.
2. Your backend creates (mints) the session with your API key (`POST /autocomplete/sessions`), forwards the page's `Origin`, and returns Baselayer's answer unchanged.
3. Each keystroke goes straight from the browser to Baselayer with that session. No cookies, no API key.
4. Picking a row hands your form its `business_token`.
5. Your backend sends the token with `POST /searches`, so the search runs on exactly the business that was picked.

The browser only ever holds a short-lived session (a few minutes) that is tied to your page's origin and has its own request budget.

## 1. Add the session endpoint to your backend

Next.js (App Router), in `app/api/ac-session/route.ts`:

```ts theme={null}
import { createMintHandler } from "@baselayer-sdk/autocomplete/server";

export const POST = createMintHandler({
  apiKey: process.env.BASELAYER_API_KEY!,
  allowedOrigins: ["https://app.example.com"],
});
```

On other backends, use `mintForOrigin({ apiKey, origin })` from the same import, and pass its status, headers and body straight through.

Put this endpoint behind your own login, like the rest of your API. Every session it mints counts against your organization's session pool.

## 2. Add the component

```tsx theme={null}
import { useState } from "react";
import { BusinessAutocomplete } from "@baselayer-sdk/autocomplete/react";
import "@baselayer-sdk/autocomplete/react/styles.css";

export function LegalNameField() {
  const [name, setName] = useState("");
  const [businessToken, setBusinessToken] = useState<string>();
  return (
    <BusinessAutocomplete
      id="legal-name"
      label="Legal entity name"
      baseUrl="https://api.baselayer.com"
      mintUrl="/api/ac-session"
      value={name}
      onChange={(value) => {
        setName(value);
        setBusinessToken(undefined); // an edit is no longer the pick
      }}
      onPick={(_, pick) => setBusinessToken(pick.businessToken)}
    />
  );
}
```

Useful options, with their defaults:

| Option | Default | What it does |
| - | - | - |
| `minChars` | `3` | Characters typed before the first request. |
| `debounceMs` | `250` | Pause after a keystroke before it is sent. |
| `limit` | `5` | Rows per keystroke, from 1 to 20. |
| `filters` | none | Narrow results, for example by state. |
| `list` | none | Lines under each row: the business's `people` and `addresses`. |
| `onUnavailable` | none | Called when sessions cannot be minted, so you can show a plain input. |

For styling, headless hooks and every option, see the [SDK site](https://sdk.baselayer.com/autocomplete/).

## 3. Send the pick with your search

From your backend, send the token on its own as the body of `POST /searches`:

```json theme={null}
{ "business_token": "…" }
```

Do not send `name` or `address` with it. The token stands in for both.

A token lasts 15 minutes from when the row was shown, and only works for your organization. If the search refuses it (expired, or the business is gone), drop the token and search by the name and address as typed. The SDK's `refusedThePin(status, code)` tells you when to do that.

## Links

* [Live demo](https://sdk.baselayer.com/autocomplete/demo/): try the components with your own API key
* [SDK overview](https://sdk.baselayer.com/autocomplete/) and [API reference](https://sdk.baselayer.com/autocomplete/api/)
* [Source on GitHub](https://github.com/osiris-ratings/baselayer-autocomplete-typescript)
* [Auto.Complete](https://docs.baselayer.com/docs/auto-complete.md): how the product works
* [Business Search: Basics](https://docs.baselayer.com/docs/business-search-basics.md): the KYB search you run on the pick

Auto.Complete is enabled per organization. Contact your Baselayer representative to turn it on.


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