API and webhook integrations

API access and outbound webhooks are available to enabled pilot workspaces. Contact your ProBB AI administrator to enable each feature. An organisation Admin manages them in Settings → Developer.

Create a keyCopy Anchor Link

Give the key a descriptive name, choose the report, analysis, job-description, interview, and event scopes your integration needs, and set an expiry from 1 to 365 days (90 by default). Copy the key when it appears: it is shown only once. Keep it in your server's secret store, never in a browser, public repository, or URL.

Keys act for the Admin who creates them. Revocation, expiry, removal, or loss of that owner's Admin role stops API access. An owner must remain a verified human account. A workspace can have ten active keys. Rotate by creating a replacement, updating your backend, then revoking the old key. Request receipts survive key rotation.

Send Authorization: Bearer YOUR_KEY to your ProBB AI application's origin. Keys belong to one workspace; IDs from another workspace are unavailable.

Analyse a candidateCopy Anchor Link

1. Prepare one PDF or DOCX with a job description.
2. PUT the file to the returned signed storage URL.
3. Get a current analysis quote and submit its fingerprint.
4. Poll status or receive a webhook, then retrieve the report.

See the API quickstart for commands and the OpenAPI contract for exact fields. Maximum file size is 10 MiB; JSON bodies are limited to 64 KiB. Inline job descriptions are limited to 50,000 characters. Bulk requests support up to 20 items and 256 KiB. Remote resume URLs are not supported. See discovery, interview, and bulk workflows and the interactive reference.

Configure notificationsCopy Anchor Link

Add a public HTTPS receiver in Settings → Developer → Webhooks, select events, and save its one-time signing secret on your server. Up to five endpoints are supported. URLs must use port 443 without URL credentials or fragments. Private addresses and redirects are rejected.

Use Send test for a synthetic event without candidate data or analysis charges. Delivery history shows status, retry time, and safe HTTP attempt details. Replay is available for retained completed/failed deliveries to the current active URL; your receiver must deduplicate their original event IDs.

Pausing stops new events for that endpoint and holds pending deliveries until resume or expiry. Events during a pause remain in the event feed. Use Preview catch-up to review and explicitly queue missing retained events for the current endpoint revision. Changing its URL cancels pending deliveries for the old URL; subscription changes apply to future events. Deleting an endpoint removes its signing secrets and cancels pending deliveries. A request already in flight may still reach the receiver.

Rotate a signing secret when needed. Both secrets sign deliveries for 24 hours, allowing receivers to update without interruption. Save the replacement immediately. Another rotation is unavailable during this overlap. Read receiver verification and recovery.

Retention and controlsCopy Anchor Link

Unadmitted upload preparations expire after 24 hours; signed upload URLs expire after ten minutes and cannot be refreshed after admission. Expired preparations and unused uploaded objects are cleaned up automatically. Accepted files follow the report/candidate retention lifecycle.

Webhook bodies and delivery history are retained for 30 days. Report deletion erases its retained notifications; organisation deletion removes integration records and secrets. Minimal event identities and request receipts remain for the workspace lifetime to prevent duplicate publication or charges. Retries never create a second charge by themselves.

API access and webhook delivery can be disabled independently. Accepted analyses continue after API access is disabled. Pending notifications wait while delivery is disabled, and retained events can be recovered through the event feed or explicit catch-up after delivery is enabled. Maintenance blocks new submissions and configuration changes while accepted work continues.