VEC.digital supports multiple certificate workflows. This guide covers the Certificate Vault API — designed for institutions that already have certificates in PDF or image format and want to upload them directly into VEC.digital for verification, QR code generation, and recipient assignment. For the complete interactive API reference, visit docs.vec.digital/api/operations/tags/certificate-vault.

Vault certificates are certificate applications with source: vault. Unlike customer-submitted applications (which go through an approval process), vault certificates are pre-approved by the institution and go straight to processing — no manual approval needed.

There are two primary integration methods available:

• API Integration — Direct HTTP requests to the VEC.digital Business API for single and bulk certificate uploads, downloads, retries, and management
• Webhook Notifications — Real-time HTTP callbacks to your server when certificate events occur (approved, failed, retried, etc.)

Your software communicates with the VEC.digital API using bearer token authentication. You upload certificate files (PDF, JPG, PNG) along with recipient metadata. Since the institution is the source, the certificate enters PROCESSING status immediately — skipping the approval queue entirely. The platform generates QR codes and verified PDFs, then handles recipient assignment: if the recipient already has a VEC.digital account, the certificate is automatically assigned; if not, they receive an email to view and share their certificate — no account required. The email also invites them to sign up; once registered with the same email, the certificate is automatically assigned to them.

The following terms are used throughout this guide. Familiarize yourself with them before proceeding.

Before integrating with the VEC.digital Certificate Vault API, ensure the following requirements are met.

Your API token must be generated from an active institution account on VEC.digital. Navigate to Institution Panel → API Tokens → Create New Token and assign the following permissions:

Webhook endpoints are configured through the VEC.digital Institution Panel (not via API). Navigate to Institution Panel → Webhooks → Endpoints → Create Webhook. Your institution user account needs the Manage Webhooks permission for dashboard access — this is separate from the API token permissions above.

Your integration environment needs one of the following:

Follow these steps in order to complete the integration. The process covers API token generation, single and bulk certificate uploads, webhook configuration, and signature verification.

Verify your token works by making a test request to list certificate templates:

A successful response returns 200 OK with a JSON array of your certificate templates. If you receive a 401 Unauthorized error, verify your token is correct.

Every API request must include these two headers:

Upload a single vault certificate with its file (PDF, JPG, JPEG, or PNG). The certificate enters processing status immediately and is handled asynchronously.

For uploading multiple certificates at once, use the two-step bulk process. First upload individual files, collect the file_id from each response, then submit all entries in a single bulk request.

Upload each certificate file and save the returned file_id:

Submit all entries referencing the collected file IDs. The bulk upload is processed asynchronously.

Use the batch_id to track processing progress through the list endpoint with status filtering.

Retrieve all vault certificates for your institution with optional filtering:

Replace {uuid} with the certificate UUID returned during upload.

If a certificate fails processing, retry it using:

Only certificates with failed status can be retried. Attempting to retry a non-failed certificate returns a 400 error.

Webhooks allow your application to receive real-time HTTP notifications when certificate events occur, eliminating the need to poll the API. Configure webhook endpoints through the Institution Panel at Institution Panel → Webhooks → Endpoints. For the full webhook documentation, see docs.vec.digital/guides/webhooks.

• Your endpoint must be publicly accessible over HTTPS
• Each institution can create up to 5 webhook endpoints
• Each webhook must subscribe to at least 1 event
• Webhook URLs must be valid HTTPS URLs (max 2048 characters)
• Configured through the Institution Panel — not via API

For detailed payload schemas for each event, see docs.vec.digital/guides/webhook-events.

Every webhook delivery contains a standardized JSON payload:

Every webhook delivery includes an HMAC-SHA256 signature in the X-Webhook-Signature header. Always verify this signature before processing the payload to ensure the request originated from VEC.digital.

• Webhooks are delivered asynchronously — your endpoint should respond quickly with a 2xx status code
• Failed deliveries (non-2xx responses or network errors) are retried up to 3 times with 30-second backoff intervals
• The last_delivery_status in the dashboard shows success, failed, or none
• The consecutive_failures counter tracks repeated failures and resets to 0 on success
• A disabled webhook (is_active: false) will not receive deliveries

• Always verify signatures before processing webhook payloads — never trust unverified requests
• Respond quickly — return a 2xx status immediately, then process the event asynchronously in your application
• Handle duplicates — webhooks may occasionally be delivered more than once; make your handler idempotent
• Use HTTPS — your endpoint must be publicly accessible over HTTPS with a valid SSL certificate
• Log deliveries — keep a record of received payloads and their signatures for debugging
• Monitor consecutive failures — check the webhook dashboard periodically for endpoints with high failure counts

Vault certificates follow a specific lifecycle. Unlike customer-submitted applications (which start at pending), vault certificates enter processing immediately:

When a vault certificate is processed:

• Recipient has a VEC.digital account: The certificate is automatically assigned to their account and they receive an assignment notification email
• Recipient does not have an account: They receive an email to view and share their certificate — no account required. The email also invites them to create a free VEC.digital account; once registered with the same email, the certificate is automatically assigned to them

This section covers common errors you may encounter during integration and their resolution steps.

For integration support, contact the VEC.digital team at support@vec.digital or visit vec.digital/support. Include your institution name, API token name (not the token itself), and the relevant request/response details when reporting issues.