API and webhooks

1. Base URL and hosts

• Production API (same host as the app): https://platform.prosvera.space/api
• Health check: https://platform.prosvera.space/health
• Interactive OpenAPI UI is available on non-production environments at /docs and /redoc.

All product data is organization-scoped. Every authenticated request must resolve to a workspace you belong to.

2. Authentication

Two mechanisms are supported.

• Session JWT (from POST /api/auth/login or /api/auth/register): Authorization: Bearer <jwt>
• Organization API key (Pro+): X-Api-Key: psv_… or Authorization: Bearer psv_…
• Organization context: X-Organization-Id: <uuid> (required when the JWT user belongs to multiple orgs; API keys are already bound to one org)

API keys are created by Owners under Settings → API keys. Keys are shown once at creation, stored hashed (SHA-256), and consume API_REQUEST usage on your plan. Rotate compromised keys immediately.

3. Roles

• OWNER - billing, API keys, webhooks, team invites, approve/send, campaign control
• ADMIN - discovery, qualification, approve/send, campaign start/pause/resume
• MEMBER - standard workspace access with fewer privileged writes

4. Core endpoint groups

Paths below are relative to /api.

• Auth: POST /auth/register, /auth/login, /auth/logout · GET /auth/me
• Organizations: GET/POST /organizations · GET /organizations/current
• ICP: GET/PUT /settings/icp
• Discovery: POST/GET /discovery/jobs · GET /discovery/results · saved-searches · company analyze/contacts
• Companies: GET/POST /companies · GET/PATCH/DELETE /companies/{id} · analyze
• Leads: GET/POST /leads · import/export · qualify · generate messages
• Messages: GET/PATCH /messages/{id} · regenerate · approve · reject · send
• Campaigns: CRUD-style /campaigns · add leads · start · pause · resume · process
• Email accounts and suppressions: /email-accounts · /suppressions · /settings/email
• Team: GET/POST /team/members
• Billing: /billing, /billing/plans, /billing/usage, checkout, portal, cancel/resume
• Analytics: /analytics · /usage · /audit-logs
• API keys: GET/POST/DELETE /api-keys
• Webhooks: GET/POST/PATCH/DELETE /webhooks · POST /webhooks/{id}/test

5. Typical automation flows

1. Create or update ICP via PUT /settings/icp.
2. Start discovery with POST /discovery/jobs using ICP fields or overrides.
3. Poll GET /discovery/jobs/{id} until COMPLETED, then read /discovery/results.
4. Qualify leads (POST /leads/{id}/qualify or bulk qualify).
5. Generate drafts, then approve/send only after human review in product or via privileged endpoints.
6. Optionally sync campaign status into your CRM with webhooks or polling /campaigns.

Do not use the API to fabricate contacts, bypass CAPTCHA, or send outreach without the product’s approval and suppression controls.

6. Outbound webhooks

Outbound webhooks are available on Business and Enterprise plans (FeatureCode webhooks). Owners create an HTTPS endpoint (http://localhost allowed in development only), optional shared secret, and the event types to subscribe to.

• discovery.completed - a discovery job finished
• lead.created - a lead was created in the workspace
• campaign.started - a campaign moved to active processing
• email.sent - an approved message was sent
• webhook.test - delivered only by the Test action

Delivery request shape: POST your URL with JSON body, User-Agent: Prosvera-Webhooks/1.0, and signature header X-Prosvera-Signature: sha256=<hex>, where <hex> is HMAC-SHA256 of the raw request body using your webhook secret. Always verify the signature before trusting the payload. Use POST /api/webhooks/{id}/test to validate your receiver.

Keep endpoints idempotent. Retries may deliver the same logical event more than once. Store event IDs when present and reject unsigned or mismatched signatures.

7. Example: verify a webhook signature (Node.js)

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header || "")
  );
}

Read the raw body bytes before JSON parsing. Compare using a constant-time function. Return 2xx only after verification succeeds so Prosvera can treat the delivery as accepted.

8. Incoming billing webhooks

Stripe (and configured billing providers) post to POST /api/billing/webhooks/{provider_name}. Those endpoints are for Prosvera’s billing stack, not for customer CRM integrations. Customer automation should use organization outbound webhooks or the REST API instead.

9. Rate limits, usage and errors

• API calls on API-enabled plans consume API_REQUEST usage.
• Discovery, contact discovery, AI credits and email sends have separate meters.
• Expect standard HTTP status codes: 401 unauthorized, 403 forbidden/plan gate, 404 missing, 422 validation, 429 usage or concurrency limits.

10. Support

For integration questions, open Help Center or Contact from a signed-in Owner account and include the endpoint, request ID if shown, and organization name. Never paste live API keys into tickets or chat.