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

# identify()

> Start a fresh identification and return its Identification ID and User HID.

Call `agent.identify()` before signup, login, checkout or another protected action. Each successful call starts a new identification, including inside the background-check cooldown.

```ts theme={null}
import { load } from '@shieldlabs-ai/js';

const agent = await load({ publicKey: 'PUBLIC_API_KEY' });
const result = await agent.identify({ userId: 'HASHED_USER_ID' });
```

For an anonymous visitor, omit `userId`:

```ts theme={null}
const result = await agent.identify();
```

## Options

**userId** `string`

A stable, pseudonymous User HID computed on your server. Omit it for anonymous checks. Empty or whitespace-only strings and the exact values `anonymous`, `fail`, `-1` and `unknown` are rejected.

Use a URL-safe opaque token or hash. The SDK warns about email-like values and identifiers containing `/`, `?`, `#`, `%`, or consisting of `.` or `..`. A warning does not transform the supplied value.

**timeout** `number`

Milliseconds to wait for initialization. Defaults to the timeout passed to [`load()`](https://docs.shieldlabs.ai/api/js-load), which is 10,000 ms unless changed. Must be greater than 0 and at most 2,147,483,647.

## Return value

`Promise<IdentifyResult>` resolves when the browser agent reports initialization:

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "HASHED_USER_ID"
}
```

**requestId** `string` *required*

Identification ID for this identification. Pass it to your backend with the protected action and use it to [retrieve the stored result](https://docs.shieldlabs.ai/api/history.md).

**userId** `string | null` *required*

The User HID supplied to this call. `null` for an anonymous identification.

Initialization does not mean scoring or storage has finished. Use bounded retries when reading a new result. See [Identification flow](https://docs.shieldlabs.ai/api/identification-flow.md).

## Errors and usage

The call rejects with `invalid_options`, `not_initialized` or `timeout`. A timeout does not establish whether a check was accepted. Retrying can start another identification and consume additional volume. See [error handling](https://docs.shieldlabs.ai/api/js-errors.md) and [usage](https://docs.shieldlabs.ai/setup/optimizing-usage.md).


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