Certificate Vault

The Certificate Vault allows institutions to upload pre-approved certificates directly, bypassing the template-based batch workflow. This is ideal for institutions that already have certificates in PDF or image format and want to issue them through VEC.digital for verification and tracking.

Key Concepts

Vault Certificate: A certificate uploaded by an institution (source: vault), as opposed to one submitted by a customer (source: customer)
Single Upload: Upload one certificate at a time with its file
Bulk Upload: Upload multiple certificates in a two-step process — first upload files, then submit entries
Auto-matching: When a vault certificate’s email matches an existing VEC.digital customer, the certificate is automatically assigned to their account

Prerequisites

To use the Certificate Vault API, your API token needs the following permissions:

certificate-vault:list — List vault certificates
certificate-vault:view — View a vault certificate
certificate-vault:create — Upload single or bulk certificates
certificate-vault:download — Download verified PDF files
certificate-vault:update — Retry failed certificates

Single Certificate Upload

Upload a single vault certificate with a certificate file (PDF, JPG, JPEG, or PNG, max 20MB):

curl -X POST \
  'https://api.vec.digital/business/certificate-vault' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'certificate_title=Certificate of Achievement' \
  -F 'full_name=John Smith' \
  -F 'applicant_email=john@example.com' \
  -F 'issue_date=2025-06-01' \
  -F 'details=Awarded for outstanding performance' \
  -F 'certificate_file=@/path/to/certificate.pdf'

Request Fields

Field	Required	Description
`certificate_title`	Yes	Title of the certificate (max 255 chars)
`full_name`	Yes	Full name of the recipient (max 255 chars)
`applicant_email`	Yes	Email address of the recipient (max 255 chars)
`issue_date`	No	Issue date in YYYY-MM-DD format
`details`	No	Additional details (max 1000 chars)
`certificate_file`	Yes	PDF, JPG, JPEG, or PNG file (max 20MB)

Duplicate Prevention

The system prevents duplicate vault certificates. A duplicate is defined as a vault certificate with the same:

Institution
Applicant email
Certificate title
Issue date (if provided)

If a duplicate is detected, you’ll receive a 422 error:

{
  "message": "A vault certificate with this email, title, and issue date already exists"
}

Response

On success (201 Created), the response includes the full certificate details:

{
  "message": "Vault certificate uploaded successfully",
  "data": {
    "id": 42,
    "uuid": "9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15",
    "reference_id": "VEC-IC-202567DAE48425BAD",
    "certificate_title": "Certificate of Achievement",
    "full_name": "John Smith",
    "applicant_email": "john@example.com",
    "source": {
      "value": "vault",
      "label": "Vault"
    },
    "status": {
      "value": "processing",
      "label": "Processing",
      "color": "warning",
      "icon": "heroicon-o-arrow-path",
      "description": "Certificate is being processed"
    },
    "issue_date": "2025-06-01",
    "institution_name": "ABC University",
    "institution_email": "admin@abcuniversity.edu",
    ...
  }
}

Bulk Upload (Two-Step Process)

For uploading multiple certificates, use the two-step bulk process:

Step 1: Upload Files

Upload each certificate file individually and collect the file_id from each response:

curl -X POST \
  'https://api.vec.digital/business/certificate-vault/upload-file' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'file=@/path/to/certificate1.pdf'

Response (201 Created):

{
  "message": "File uploaded successfully",
  "data": {
    "file_id": "9e3b101f-c264-4f97-945f-20dfa7163768",
    "file_name": "certificate1.pdf",
    "mime_type": "application/pdf",
    "size": 245760
  }
}

Save the file_id — you’ll need it in Step 2.

Step 2: Submit Bulk Entries

Once all files are uploaded, submit the bulk request with entries referencing the file IDs:

curl -X POST \
  'https://api.vec.digital/business/certificate-vault/bulk' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'entries[0][certificate_title]=Certificate of Achievement' \
  -F 'entries[0][full_name]=John Smith' \
  -F 'entries[0][applicant_email]=john@example.com' \
  -F 'entries[0][file_id]=9e3b101f-c264-4f97-945f-20dfa7163768' \
  -F 'entries[0][issue_date]=2025-06-01' \
  -F 'entries[0][details]=Batch entry #1' \
  -F 'entries[1][certificate_title]=Certificate of Excellence' \
  -F 'entries[1][full_name]=Jane Doe' \
  -F 'entries[1][applicant_email]=jane@example.com' \
  -F 'entries[1][file_id]=8d2a0f9e-b1c3-4d86-a570-f12345678901' \
  -F 'entries[1][issue_date]=2025-06-01' \
  -F 'entries[1][details]=Batch entry #2'

Response (202 Accepted):

{
  "message": "Bulk vault upload queued for processing",
  "data": {
    "batch_id": "8f7d6e5c-4b3a-2910-z987-y654x321w000",
    "total": 2,
    "status": "processing"
  }
}

The bulk upload is processed asynchronously. Use the batch_id to track progress through the list endpoint.

Bulk Entry Fields

Field	Required	Description
`entries[].certificate_title`	Yes	Title of the certificate (max 255 chars)
`entries[].full_name`	Yes	Full name of the recipient (max 255 chars)
`entries[].applicant_email`	Yes	Email address of the recipient (max 255 chars)
`entries[].file_id`	Yes	UUID from the upload-file step
`entries[].issue_date`	No	Issue date in YYYY-MM-DD format
`entries[].details`	No	Additional details (max 1000 chars)

Listing Vault Certificates

List all vault certificates for your institution:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Filtering

By status:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault?status=failed' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

By email:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault?applicant_email=john@example.com' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Search by name, email, title, or reference ID:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault?search=John' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Viewing a Vault Certificate

Retrieve details for a specific vault certificate:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Downloading a Vault Certificate

Download the verified PDF of a vault certificate:

curl -X GET \
  'https://api.vec.digital/business/certificate-vault/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/download' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --output certificate.pdf

If the certificate is still processing, you’ll receive a 404 response:

{
  "message": "Verified PDF not found. The certificate may still be processing."
}

Retrying Failed Certificates

If a vault certificate fails processing, you can retry it:

curl -X POST \
  'https://api.vec.digital/business/certificate-vault/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/retry' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

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

Notification Behavior

When a vault certificate is processed:

If the recipient has a VEC.digital account: An assigned notification is sent to their account email
If the recipient does not have an account: An invitation email is sent with a link to create a free account and claim their certificate

Vault vs. Batch Certificates

Feature	Vault	Batch (Template-based)
Source	`vault`	`customer`
Upload method	Direct file upload	CSV with template
Template needed	No	Yes
Institution details	Auto-filled from account	From CSV
Duplicate check	Email + Title + Issue Date	CSV-based
Processing	Auto after upload	Batch processing
Typical use case	Pre-existing certificates	New certificates from template