Batch Processing

Batch Processing

The VEC.digital API allows you to create and issue certificates in batches, which is an efficient way to generate multiple certificates at once. This guide explains how to work with batches through the API.

Batch Lifecycle

A certificate batch in VEC.digital goes through several states:

1. Pending: The batch has been created but processing hasn’t started
2. Processing: The certificates are being generated
3. Waiting for Approval: The batch requires signatures or approvals
4. Completed: All certificates in the batch have been successfully created
5. Partially Completed: Some certificates were created successfully, but others failed
6. Failed: The batch processing failed

Creating a Batch

To create a batch, you need:

1. A template ID (from an existing certificate template)
2. A CSV file containing recipient information
3. Optional signatories if your certificates require signatures

CSV File Format

Your CSV file must include at least these headers:

• RecipientsEmail: Email address of the certificate recipient
• RecipientsName: Full name of the certificate recipient

You can also include additional columns for custom data to be included in the certificates.

Example CSV:

RecipientsEmail,RecipientsName,CourseTitle,CompletionDate
john@example.com,John Smith,Advanced Web Development,2025-02-15
mary@example.com,Mary Johnson,Advanced Web Development,2025-02-15

API Request

Create a batch using a POST request to /business/batches:

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

If your certificates require signatures, you can specify signatories:

curl -X POST \
  'https://api.vec.digital/business/batches' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'name=Web Development Graduates 2025' \
  -F 'template_id=9e3b101f-c264-4f97-945f-20dfa7163768' \
  -F 'csv_file=@/path/to/recipients.csv' \
  -F 'signatories[0][institution_user_id]=3' \
  -F 'signatories[0][signatory_index]=1' \
  -F 'signatories[1][institution_user_id]=17' \
  -F 'signatories[1][signatory_index]=2'

Monitoring Batch Status

After creating a batch, you can monitor its status using the batch status endpoint:

curl -X GET \
  'https://api.vec.digital/business/batches/9e7860e3-7c0a-401f-98f6-b98e316934f4/status' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

The response will include:

• Current batch status
• Total number of certificates
• Number of processed certificates
• Number of failed certificates
• Progress percentage

Example response:

{
  "status": "processing",
  "total_certificates": 50,
  "processed_certificates": 25,
  "failed_certificates": 0,
  "progress": 50.0
}

Retrieving Batch Details

To get detailed information about a batch, including its associated template:

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

Listing Certificates in a Batch

To view all certificates created from a specific batch:

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'

Common Issues and Troubleshooting

Batch Creation Failures

If batch creation fails, check:

1. CSV Format: Ensure your CSV has the required headers and is properly formatted
2. Template ID: Verify the template ID exists and is accessible to your institution
3. Balance: Confirm you have sufficient certificate credits in your account

Signature Requirements

If your certificates are in the “Waiting for Approval” status:

1. Signatories must log in to the VEC.digital platform
2. They should navigate to their pending signatures
3. They can approve or reject the certificates

Failed Certificates

If some certificates fail in a batch:

1. Check the CSV data for any errors or missing information
2. Verify that all recipients have valid email addresses
3. Consider recreating the batch with corrected data

Best Practices

• Name batches descriptively: Use naming conventions that help you identify batches easily
• Keep CSVs manageable: Limit batches to a reasonable size (we recommend up to 1000 certificates per batch)
• Test small batches first: Before uploading large batches, test with a small number of recipients
• Monitor status: Regularly check batch status for long-running batches
• Include custom data: Leverage the CSV to include custom data for more personalized certificates