Skip to content
VEC Digital API

Create a new batch

POST
/business/batches

Creates a new certificate batch with the provided CSV file and template.

Authorizations

Request Body required

object
name
required

Name of the batch

string
Class 10th, 2024
template_id
required

UUID of the certificate template to use

string format: uuid 
9e3b101f-c264-4f97-945f-20dfa7163768
csv_file
required

CSV file containing recipient information. Must include headers RecipientsEmail and RecipientsName.

string format: binary
signatories

Optional array of signatories for the certificates

Array<object>
object
user_uuid
required

UUID of the institution user who will sign

string format: uuid 
66c9c977-f379-4692-9d5c-f989c17543ee
index
required

Order index of the signature (starting from 1, must be sequential without gaps)

integer
1

Responses

201

Batch created successfully

object
data
object
id

Unique identifier for the batch

string format: uuid 
9e7860e3-7c0a-401f-98f6-b98e316934f4
name

Name of the batch

string
Class 10th, 2024
status

Current status of the batch

string
Allowed values: pending processing completed partially_completed failed waiting_for_approval 
completed
template_id

ID of the certificate template used

string format: uuid 
9d76a768-d016-4364-b18b-32c647adad0c
total_certificates

Total number of certificates in the batch

integer
1
processed_certificates

Number of successfully processed certificates

integer
1
failed_certificates

Number of failed certificates

integer
0
progress

Progress percentage (0-100)

number format: float 
100
completion_date

When the batch was completed

string format: date-time
nullable 
2025-03-14T13:04:03.000000Z
created_at

Creation timestamp

string format: date-time 
2025-03-14T13:02:19.000000Z
updated_at

Last update timestamp

string format: date-time 
2025-03-14T13:04:03.000000Z
template
object
id

Unique identifier for the template

string format: uuid 
9e3b101f-c264-4f97-945f-20dfa7163768
institution_id

ID of the institution that owns this template

integer
3
name

Name of the template

string
Certificate 2
screenshot

URL to the template screenshot

string format: uri 
https://api.vec.digital/storage/certificate_templates/67ca927729685_1741329015.png
created_at

Creation timestamp

string format: date-time 
2025-02-17T04:05:07.000000Z
updated_at

Last update timestamp

string format: date-time 
2025-03-07T06:30:15.000000Z
requires_signatures

Whether this batch requires signatures

boolean
true
requires_my_signature

Whether this batch requires the current user’s signature

boolean

401

Authentication failed

object
message

Error message

string
Unauthorized - Invalid API token

403

Permission denied

object
message

Error message

string
Forbidden - Insufficient permissions
required_permission

Required permission to access this resource

string
batches:view

422

Batch creation validation failed

object
message

Error summary

string
The name field is required. (and 2 more errors)
errors

Detailed validation errors

object
key
additional properties
Array<string>
{
  "name": [
    "The name field is required."
  ],
  "template_id": [
    "The selected template id is invalid."
  ],
  "csv_file": [
    "The csv file field is required."
  ],
  "signatories": [
    "The same signatory cannot be assigned to multiple positions."
  ],
  "signatories.0.index": [
    "Signatory indices must start from 1."
  ],
  "signatories.1.index": [
    "Signatory indices must be sequential starting from 1 without gaps."
  ]
}

500

Server error

object
message

Error message

string
An unexpected error occurred. Our team has been notified.
error_code

Error code

string
SERVER_ERROR