Skip to content
VEC Digital API

Getting Started

Getting Started with VEC.digital API

This guide will help you get started with integrating the VEC.digital API into your application. Follow these steps to begin issuing digital certificates through your application.

Prerequisites

Before you begin, you need:

  1. A VEC.digital account with an institution role
  2. API access permissions for your account
  3. API token generated from your VEC.digital dashboard

If you don’t have these, sign up at vec.digital and contact support if you need help with API access.

Overview of the Integration Process

The typical integration process follows these steps:

  1. Authentication: Set up API authentication using your token
  2. Template Selection: Choose or create a certificate template
  3. Batch Processing: Create a batch of certificates from a CSV file
  4. Monitoring: Track the status of your certificate batch
  5. Certificate Management: Access and download the generated certificates

Quick Start

Here’s a quick example of how to list your certificate templates:

// Example using JavaScript (Node.js with axios)
const axios = require('axios');


const API_TOKEN = 'YOUR_API_TOKEN';
const BASE_URL = 'https://api.vec.digital';


async function listCertificateTemplates() {
  try {
    const response = await axios.get(`${BASE_URL}/business/certificate-templates`, {
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${API_TOKEN}`
      }
    });


    console.log('Templates:', response.data.data);
    return response.data;
  } catch (error) {
    console.error('Error fetching templates:', error.response?.data || error.message);
    throw error;
  }
}


// Execute the function
listCertificateTemplates();

Step 1: Authentication

First, set up authentication by creating an API token:

  1. Log in to your VEC.digital account
  2. Navigate to Settings > API Tokens
  3. Create a new API token with appropriate permissions
  4. Copy the token and store it securely

Use this token in the Authorization header of all API requests:

Authorization: Bearer YOUR_API_TOKEN

For more details, see the Authentication Guide.

Step 2: Choose a Certificate Template

Before creating certificates, you need to select a template. List available templates:

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

The response will include template IDs, names, and screenshots. Note the ID of the template you want to use.

Step 3: Prepare Your CSV Data

Create a CSV file with recipient information. At minimum, include:

RecipientsEmail,RecipientsName
john@example.com,John Smith
jane@example.com,Jane Doe

You can add additional columns for custom fields in your certificates.

Step 4: Create a Certificate Batch

Create a batch using your template ID and CSV file:

Terminal window
curl -X POST \
  'https://api.vec.digital/business/batches' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'name=My First Batch' \
  -F 'template_id=9e3b101f-c264-4f97-945f-20dfa7163768' \
  -F 'csv_file=@/path/to/recipients.csv'

The response will include a batch ID. Note this ID for tracking.

Step 5: Monitor Batch Status

Check the status of your batch to determine when it’s finished processing:

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

The batch will go through various states: pending, processing, and eventually completed or partially_completed if there were any issues.

Step 6: Access Generated Certificates

Once the batch is complete, list all certificates in the batch:

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

To download a specific certificate as a PDF:

Terminal window
curl -X GET \
  'https://api.vec.digital/business/certificates/CERTIFICATE_ID/download' \
  -H 'Accept: application/pdf' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --output certificate.pdf

Error Handling

The API returns appropriate HTTP status codes and error messages:

  • 400 - Bad Request: Invalid parameters
  • 401 - Unauthorized: Invalid or missing API token
  • 403 - Forbidden: Insufficient permissions
  • 404 - Not Found: Requested resource doesn’t exist
  • 422 - Unprocessable Entity: Validation errors
  • 500 - Server Error: Something went wrong on our end

Always check the response status and implement proper error handling in your application.

Rate Limiting

The API implements rate limiting to ensure fair usage. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Implement backoff strategies in your application to handle this gracefully.

Next Steps

Explore these guides for more detailed information:

With this foundation, you’re ready to integrate VEC.digital into your application and start issuing beautiful certificates!