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

# identifyOnInteraction()

> Start identification on form interaction and retrieve a fresh result when submitting.

`agent.identifyOnInteraction()` starts identification when a visitor first interacts with an element. Call `take()` when submitting to obtain that result or start a fresh check.

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

const agent = await load({ publicKey: 'PUBLIC_API_KEY' });
const form = document.querySelector<HTMLFormElement>('#signup');
if (!form) throw new Error('Signup form not found');

const identification = agent.identifyOnInteraction(form);
```

## Arguments

**target** `EventTarget` *required*

The form or element to observe. It must support `addEventListener` and `removeEventListener`. The agent listens for `focusin`, `pointerdown` and `keydown`.

**options** `IdentifyOptions`

Optional `userId` and `timeout`, with the same rules as [`identify()`](https://docs.shieldlabs.ai/api/js-identify#options). Recreate the handle if the signed-in user changes.

## Returned handle

The method synchronously returns an `InteractionIdentifier` with two methods:

**take()** `Promise\<IdentifyResult\>` *required*

Returns an in-flight or successful early identification while it is fresh. Starts a new identification if none exists, the earlier one failed, or it completed at least four minutes ago. Each call re-arms the handle for the next submission.

**dispose()** `void` *required*

Removes the listeners and drops the retained result. Call it when the form is removed or the component unmounts. It does not cancel a check already in progress.

Use `take()` in your existing submit handler before forwarding the protected action:

```ts theme={null}
const { requestId: identificationId } = await identification.take();
// Include identificationId in the request to your backend.
```

Remove the listeners during cleanup:

```ts theme={null}
identification.dispose();
```

## Refresh and errors

While interactions continue, a completed early result can be replaced after four minutes. After an early failure, another interaction can retry after five seconds. This is interaction-driven, not a background polling timer. Each identification that runs consumes volume, even if the form is never submitted.

Invalid arguments throw `invalid_options` synchronously. `take()` returns a promise that can reject with the [identification errors](https://docs.shieldlabs.ai/api/js-errors.md). Handle rejection before completing the protected action.


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