Create a new batch

POST

/business/batches

• production API Server

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

Authorizations

• ApiKeyAuth

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. Required headers: RecipientsEmail, RecipientsName. Optional reserved header: IssueDate (format DD-MM-YYYY, e.g. 15-02-2025). If omitted, the current date is used. Any additional columns are treated as custom certificate data.

string format: binary

signatories

Optional array of signatories. Required if the template has signatory fields and no default signatories are configured. Indices must start from 1 and be sequential without gaps. The same user cannot appear in multiple positions. If omitted and the template has default signatories configured, they will be used automatically.

Array<object>

object

user_uuid

required

UUID of the institution user who will sign. The user must have a signature uploaded and must not be archived.

string format: uuid

66c9c977-f379-4692-9d5c-f989c17543ee

index

required

Position 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

has_signatures

Whether this template has signatory fields. If true, signatories must be provided (or default signatories configured) when creating a batch.

boolean

true

has_default_signatories

Whether this template has default signatories configured. If true, you can create a batch without providing signatories.

boolean

requires_signature_setup

True when the template has signatory fields but no default signatories are configured. You must provide signatories explicitly when creating a batch with this template.

boolean

true

signatory_fields

List of signatory field identifiers defined in the template canvas.

Array<string>

[
  "signatory_1",
  "signatory_2"
]

default_signatories

Default signatories configured for this template. Only present when has_default_signatories is true.

Array<object>

nullable

object

id

integer

1

signatory_index

integer

1

institution_user_id

integer

3

display_name

string

nullable

Faizan Ali

designation

string

nullable

Software Developer

auto_approve

boolean

user

object

id

integer

3

uuid

string format: uuid

66c9c977-f379-4692-9d5c-f989c17543ee

first_name

string

Faizan

last_name

string

Ali

email

string format: email

faizan@example.com

signatory_name

string

nullable

Faizan Ali

signatory_designation

string

nullable

Software Developer

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