PolicyNest
Sign inGet started

API Documentation

Build integrations with the PolicyNest REST API

API Access requires a Pro or Agency plan

API keys can only be generated on the Pro or Agency plan. To get started, upgrade your plan in Settings → Billing. Already on Pro? Generate your API key.

RESTful

Standard REST conventions with JSON request/response bodies and proper HTTP status codes.

Secure

API key authentication with SHA-256 hashing. All data is scoped to your agent account and tenant.

Rate Limited

100 requests per minute per API key. Rate limit headers included in every response.

Authentication

Getting an API Key

API key generation requires a Pro or Agency plan.Upgrade your plan →

  1. Navigate to Settings in the sidebar
  2. Click the Integrations tab
  3. Under API Keys, click Generate Key
  4. Give your key a descriptive label (e.g., "GHL Integration")
  5. Copy the key immediately — it will only be shown once

Using the API Key

Include your API key in the Authorization header of every request:

curl -X GET "https://policynest-mu.vercel.app/api/v1/clients" \
  -H "Authorization: Bearer pn_your_api_key_here" \
  -H "Content-Type: application/json"

Security Best Practices

  • Never expose your API key in client-side code or public repositories
  • Store keys in environment variables or a secrets manager
  • Rotate keys periodically and revoke unused keys
  • Each key is scoped to a single agent — use separate keys for different integrations

Base URL

https://policynest-mu.vercel.app/api/v1

All endpoints are relative to this base URL. Responses are JSON with UTF-8 encoding.

Response Format

All responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Error Response

{
  "success": false,
  "error": "Description of what went wrong"
}

HTTP Status Codes

CodeMeaning
200Success
400Bad request (invalid parameters or body)
401Unauthorized (missing or invalid API key)
403Forbidden (resource not in your portfolio)
404Resource not found
429Rate limit exceeded (100 req/min)
500Internal server error

Rate Limit Headers

Every response includes these headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per window (100)
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait (only on 429 responses)

Endpoints

Inbound Webhooks

PolicyNest can receive leads automatically from external platforms via webhook. Each source has a dedicated adapter that normalises the payload into a standard lead record and routes it to your account.

Webhook URL Pattern

Send a POST request to the following URL, replacing :source with one of the supported source identifiers below:

https://policynest-mu.vercel.app/api/v1/webhooks/leads/:source

Supported Sources

SourceURLNotes
ghl/api/v1/webhooks/leads/ghlGoHighLevel — maps contact.firstName, contact.lastName, contact.email, contact.phone
zapier/api/v1/webhooks/leads/zapierZapier webhooks — standard field mapping with camelCase or snake_case support
facebook/api/v1/webhooks/leads/facebookFacebook Lead Ads — supports X-Hub-Signature-256 verification
generic/api/v1/webhooks/leads/genericAny platform — flexible field mapping, use for custom integrations

Authentication

Authenticate webhook requests using your API key in one of two ways:

Option A — Authorization header (preferred)

curl -X POST "https://policynest-mu.vercel.app/api/v1/webhooks/leads/generic" \
  -H "Authorization: Bearer pn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Doe","email":"jane@example.com"}'

Option B — Query parameter (for platforms that can't set headers)

curl -X POST "https://policynest-mu.vercel.app/api/v1/webhooks/leads/zapier?api_key=pn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","email":"jane@example.com"}'

Webhook Response

{
  "success": true,
  "data": {
    "leadId": "lead_abc123",
    "action": "created",
    "source": "generic"
  }
}

Manage your API keys & view webhook logs

Generate API keys, rotate or revoke them, and monitor incoming webhook activity in the Integrations hub.

Go to Settings → Integrations

API Keys & Webhook Logs

API keys are generated and managed in Settings → Integrations. From there you can:

  • Generate new API keys with descriptive labels (e.g. “GHL Integration”, “Zapier”)
  • Revoke compromised or unused keys immediately
  • Monitor incoming webhook events — status, payload preview, and timestamps
  • Follow the step-by-step Setup Guide for GHL, Zapier, and Facebook integrations
Open Integrations Hub

Need help? Visit Settings → Integrations to manage your API keys, or contact support for integration assistance.

PolicyNest API v1 — Last updated March 2026