DevelopersSelf HostingAI Recipient & Field Detection

AI Recipient & Field Detection (Self-hosting)

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 and manage keys in 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"

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.

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:

Organisation settings

Go to Settings → Document Preferences → AI Features and set to Enabled. Teams that inherit organisation defaults will pick this up.

Team settings

If a team overrides organisation defaults, go to Team Settings → Document Preferences → AI Features and choose Enabled (or Inherit to follow the organisation).

Verify in the editor

Open a draft envelope. In Recipients, you should see the sparkle button for AI detection. In Fields, you should see Detect with AI available.

Troubleshooting

  • Too many requests: Wait a minute or two and retry (rate limit is 3/min per IP).
  • AI options hidden: Ensure the env vars are set, the server was restarted after setting them, and aiFeaturesEnabled is enabled at organisation/team level.
  • 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.

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

TelemetryGetting Started