Skip to content
VEC Digital API

Working with Certificates

Working with Certificates

The VEC.digital API provides endpoints to manage individual certificates, allowing you to list, view, and download certificates. This guide covers the essentials of working with certificates through the API.

Certificate Structure

Each certificate in VEC.digital has:

  • A unique identifier (UUID)
  • A reference ID (used for public verification)
  • Recipient information (name and email)
  • File paths (PDF, image, QR code, and barcode)
  • Status information
  • Signature details (if applicable)
  • Metadata (issue date, generation date, etc.)

Listing Certificates

You can retrieve all certificates for your institution with:

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

Filtering and Sorting

The certificates endpoint supports various filtering and sorting options:

Search by name, email, or reference ID:

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

Filter by Status

Filter by certificate status:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates?status=generated' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Possible status values: pending, processing, generated, failed, revoked

Filter by Date Range

Filter by issue date or generation date:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates?issue_date_from=2025-01-01&issue_date_to=2025-03-31' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Filter by Batch or Customer

Filter by batch ID:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates?batch_id=9e7860e3-7c0a-401f-98f6-b98e316934f4' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Filter by customer ID:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates?customer_id=12' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Sorting

Sort by various fields:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates?sort_field=created_at&sort_order=desc' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Available sort fields: name, email, status, issue_date, generated_at, created_at, updated_at

Viewing Certificate Details

To retrieve detailed information about a specific certificate:

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

This will return comprehensive certificate information including:

  • Basic certificate details
  • Associated batch information
  • Signature information (if applicable)
  • Creator information

Downloading Certificates

To download a certificate as a PDF:

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

Working with Certificate Assets

Each certificate has several associated assets:

  • PDF: The complete certificate in PDF format
  • Image: A PNG rendering of the certificate
  • QR Code: A QR code that links to the certificate verification page
  • Barcode: A barcode for verification purposes

The URLs for these assets are included in the certificate details response:

{
  "data": {
    "id": "9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15",
    "pdf_path": "https://api.vec.digital/storage/certificates/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/certificate_1742398957.pdf",
    "image_path": "https://api.vec.digital/storage/certificates/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/certificate_1742398953.png",
    "qrcode_path": "https://api.vec.digital/storage/certificates/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/qr_code_1742398952.svg",
    "barcode_path": "https://api.vec.digital/storage/certificates/9e7860f0-05d1-4fd0-b3e0-e98e19f1cf15/barcode_1742398952.svg",
    // ...other fields
  }
}

Certificate Signatures

If a certificate requires signatures, the certificate details will include signature information:

{
  "data": {
    // ...other fields
    "total_signatures": 2,
    "approved_signatures": 1,
    "signatures": [
      {
        "id": 46,
        "institution_user_id": 3,
        "display_name": "Faizan Ali",
        "designation": "Software Developer",
        "signatory_index": 1,
        "status": "approved",
        "approved_at": "2025-03-13T14:55:38.000000Z"
        // ...other fields
      },
      {
        "id": 47,
        "institution_user_id": 17,
        "display_name": null,
        "designation": null,
        "signatory_index": 2,
        "status": "pending",
        "approved_at": null
        // ...other fields
      }
    ]
  }
}

Certificate Verification

Each certificate has a unique reference ID that can be used for public verification:

VEC-IC-202567DAE48425BAD

This reference ID can be shared with anyone who needs to verify the certificate’s authenticity. They can use it on the VEC.digital verification page.

Best Practices

  • Cache certificate information: When displaying certificate information in your application, consider caching it to reduce API calls
  • Check signatures: Before distributing certificates, ensure all required signatures have been approved
  • Provide verification links: Include the certificate reference ID or verification URL when distributing certificates
  • Use appropriate pagination: When listing certificates, use the pagination parameters to limit the number of results returned
  • Reference certificates by UUID: Always use the certificate UUID when referencing certificates in API calls