---
title: AI Recipient & Field Detection (Self-hosting)
description: Configure Google Vertex AI so Documenso can detect recipients and fields automatically.
---

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Overview

This guide covers how to enable the AI recipient and field detection features when you self-host Documenso.

## What This Enables

- Detect recipients from uploaded PDFs (roles, names, emails when present).
- Detect and place fields (signature, initials, name, email, date, text, number, radio, checkbox) onto draft envelopes.
- Built-in rate limits (3 requests per minute per IP) to prevent abuse.

## Prerequisites

- A Google Cloud project with the **Vertex AI API** enabled and billing active.
- A **Vertex AI Express API key** with access to Gemini models (create via the [Vertex AI Express flow](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) and manage keys in [API keys](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys)).
- Documenso version that includes the AI detection feature and the corresponding database migration.

## Configure Environment Variables

Add these variables to your deployment `.env` (or secret manager):

```
GOOGLE_VERTEX_PROJECT_ID="<your-gcp-project-id>"
GOOGLE_VERTEX_API_KEY="<your-vertex-api-key>"
# Optional, defaults to "global"
GOOGLE_VERTEX_LOCATION="global"
```

<Callout type="info">
  Use a region close to your users if you need data residency considerations (e.g. `europe-west1`).
  If you omit the location, Documenso uses `global`. Not all models are available in every region;
  if a model is unavailable, switch to a supported region.
</Callout>

## Deploy with the Published Container

- Use the official Documenso image (DockerHub or GHCR) and supply the Vertex env vars above.
- Ensure migrations run on startup (the container runs `prisma migrate deploy` in production mode).
- Restart the container after adding or changing Vertex env vars.

## Enable the Feature in Documenso

Once the service is running with the Vertex env vars:

{/* prettier-ignore */}
<Steps>
<Step>
### Organisation settings

Go to **Settings** → **Document Preferences** → **AI Features** and set to **Enabled**.

Teams that inherit organisation defaults will get this automatically.

</Step>
<Step>
### Team settings

If a team overrides organisation defaults:

- Go to **Team Settings** → **Document Preferences** → **AI Features**
- Choose **Enabled**, or **Inherit** to follow the organisation

</Step>
<Step>
### Verify in the editor

Open a draft envelope and check:

- **Recipients**: sparkle button for AI detection is visible
- **Fields**: **Detect with AI** is available

</Step>
</Steps>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Too many requests">
    Wait a minute or two and retry (rate limit is 3/min per IP).
  </Accordion>
  <Accordion title="AI options hidden">
    Ensure the env vars are set, the server was restarted after setting them, and
    `aiFeaturesEnabled` is enabled at organisation/team level.
  </Accordion>
  <Accordion title="Detection fails immediately">
    Confirm the Vertex API key is valid and the project has Vertex AI enabled. Check server logs for
    status codes from Vertex.
  </Accordion>
</Accordions>

If issues persist, recheck env vars, restart the service, and confirm the Prisma migration was applied.

---

## See Also

- [AI Detection (User Guide)](/docs/users/documents/advanced/ai-detection) - How to use AI detection features
- [Environment Variables](/docs/self-hosting/configuration/environment) - All configuration options