Certiverse Voucher Partner API

Version: 1.0

Base Path: /api

Auth: Pattern B (Direct Bearer)

 

Returns a paginated list of voucher partners. All query parameters are optional; omitting all filters returns all accessible partners.

Request Headers

Header	Value	Required
Authorization	Bearer <token>	Required

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number. Defaults to 1.
partnerName	string	Optional	Filter by partner name. Partial matches may be supported.
status	string	Optional	Filter by partner status. ActiveArchivedInactive

Response — 200 OK

Property	Type	Nullable	Description
data	PartnerVoucherPartnerModel[]	No	List of matching voucher partners.
nextLink	string	Nullable	URL to the next page. Absent when no further pages exist.

PartnerVoucherPartnerModel — data[]

Property	Type	Nullable	Description
id	string	No	Unique identifier.
isActive	boolean	No	Whether the partner is currently active.
isArchived	boolean	No	Whether the partner has been archived.
name	string	No	Display name.
users	PartnerVoucherPartnerUserModel[]	No	Users associated with this partner.

PartnerVoucherPartnerUserModel — users[]

Property	Type	Nullable	Description
email	string	No	Email address of the partner user.
isActive	boolean	No	Whether the user account is active.
status	string	No	Current status (e.g., Active, Inactive).

HTTP Status Codes

Code	Description
200	Success.
400	Bad Request — invalid status value.
401	Unauthorized.
422	Unprocessable Entity - Exceeded the 10,000 record limit
500	Internal Server Error.

 

Voucher Programs

GET /api/vouchers/programs

Returns a paginated list of voucher programs. Each program includes its store exams, partner assignments, discount tiers, and restriction settings.

Request Headers

Header	Value	Required
Authorization	Bearer <token>	Required

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number. Defaults to 1.
programName	string	Optional	Filter by program name. Partial matches may be supported.

Response — 200 OK

Property	Type	Nullable	Description
data	PartnerVoucherProgramModel[]	No	List of matching voucher programs.
nextLink	string	Nullable	URL to the next page.

PartnerVoucherProgramModel — data[]

Property	Type	Nullable	Description
allowAchPayments	boolean	No	Whether ACH (bank transfer) payments are accepted.
discounts	PartnerVoucherProgramDiscountModel[]	No	Bulk discount tiers.
expirationPeriodInDays	integer	No	Days after issuance before a voucher expires.
id	string	No	Unique identifier.
isActive	boolean	No
isArchived	boolean	No
isInactive	boolean	No
name	string	No	Display name.
partners	PartnerVoucherProgramPartnerModel	No	Partner assignment and pricing configuration.
restrictions	PartnerVoucherProgramRestrictionsModel	No	Booking restrictions applied to vouchers.
storeExams	PartnerVoucherProgramStoreExamModel[]	No	Exams available under this program.
voucherCodePrefix	string	No	Prefix applied to generated voucher codes.

PartnerVoucherProgramDiscountModel — discounts[]

Property	Type	Description
id	string	Unique identifier for the discount tier.
percent	decimal	Discount percentage when the threshold is met.
quantity	integer	Minimum quantity to qualify for this discount.

PartnerVoucherProgramPartnerModel — partners

Property	Type	Description
assignedPartners	PartnerVoucherProgramAssignedPartnerModel[]	Partners explicitly assigned to this program.
canAssignedPartnersPurchaseZeroPrice	boolean	Whether assigned partners can purchase vouchers at zero cost.
isAvailableToAllVoucherPartners	boolean	If true, open to all partners. If false, only assigned partners may participate.
partnerCostPerVoucher	decimal	Cost per voucher charged to the partner.

PartnerVoucherProgramRestrictionsModel — restrictions

Property	Type	Description
emailDomainRestrictions	PartnerVoucherProgramEmailDomainRestrictionModel[]	Domain-level restrictions on who may redeem vouchers.
enforceAssignedEmailToBookExam	boolean	If true, the voucher's assigned recipient email must match the booking account.

PartnerVoucherProgramStoreExamModel — storeExams[]

Property	Type	Description
code	string	Short exam code.
id	string	Unique identifier.
name	string	Exam display name.
price	decimal	Retail price of the exam.

HTTP Status Codes

Code	Description
200	Success.
401	Unauthorized.
422	Unprocessable Entity - Exceeded the 10,000 record limit
500	Internal Server Error.

Voucher Purchases

GET /api/vouchers/purchases

Returns a paginated list of voucher purchase records, including quantity, pricing, and status. At least one filter parameter (other than page) must be provided.

At least one of the following is required: purchaseCode, partnerName, programName, purchasedByEmail, or status. Providing only page returns a 400 Bad Request.

Request Headers

Header	Value	Required
Authorization	Bearer <token>	Required

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number. Defaults to 1.
partnerName	string	Conditional	Filter by the name of the partner who made the purchase.
programName	string	Conditional	Filter by voucher program name.
purchaseCode	string	Conditional	Filter by voucher purchase code.
purchasedByEmail	string	Conditional	Filter by buyer email. Must be a valid email format.
status	string	Conditional	Filter by purchase status. CheckoutCancelled CheckoutExpired CheckoutFailed CheckoutInProgress CompleteVoucherCreation

Response — 200 OK PartnerVoucherPurchaseModel — data[]

Property	Type	Nullable	Description
amountPaid	decimal	No	Total amount paid.
id	string	No	Unique identifier for the purchase record.
isArchived	boolean	No	Whether this purchase record has been archived.
notes	string	No	Notes recorded against this purchase.
partnerName	string	No	Name of the partner who made the purchase.
programName	string	No	Name of the voucher program purchased.
purchaseDateUtc	string (ISO 8601)	No	Date/time the purchase was initiated, UTC.
purchasedByFirstName	string	No	First name of the purchasing user.
purchasedByLastName	string	No	Last name of the purchasing user.
quantity	integer	No	Total vouchers purchased.
quantityRemaining	integer	No	Vouchers remaining unused.
quantityUsed	integer	No	Vouchers redeemed.
status	string	No	Current purchase status.
voucherPurchaseCode	string	No	Human-readable code identifying this purchase.

HTTP Status Codes

Code	Description
200	Success.
400	Bad Request — no filter parameters provided; invalid status; invalid email format.
401	Unauthorized.
422	Unprocessable Entity - Exceeded the 10,000 record limit
500	Internal Server Error.

POST /api/vouchers/purchases

Creates a new voucher purchase for the authenticated partner. Upon success, the system queues voucher generation and returns the created purchase record.

This endpoint only supports voucher programs priced at $0. Attempting to purchase a program with a non-zero price will result in a 400 Bad Request.

Request Headers

Header	Value	Required
Authorization	Bearer <token>	Required
Content-Type	application/json	Required

Request Body — VoucherPurchaseCreateCommand

Property	Type	Required	Validation	Description
notes	string	Required	Non-empty	Notes to associate with this purchase record.
partnerName	string	Required	Non-empty	Name of the partner making the purchase. Must match an active partner within your organization.
programName	string	Required	Non-empty	Name of the voucher program to purchase from. Must match an active program.
quantity	integer	Required	1–1000	Number of vouchers to purchase.

{   "notes": "Q2 employee certification batch",   "partnerName": "Acme Corp",   "programName": "Spring Certification Drive",   "quantity": 50 } Response — 200 OK

Returns a single PartnerVoucherPurchaseModel representing the newly created purchase. The schema is identical to a single item in the GET /vouchers/purchases data[] array, listed above.

Note on purchasedByFirstName / purchasedByLastName: Purchases made via this API are attributed to the system user "Certiverse API" rather than an individual person. These fields will reflect that system name.

HTTP Status Codes

Code	Description
200	Success. Returns the created PartnerVoucherPurchaseModel.
400	Bad Request — validation failure, partner or program not found, or program price is not $0.
401	Unauthorized.
500	Internal Server Error.

GET /api/vouchers

Returns a paginated list of individual vouchers with assignment, usage, and reservation details. At least one filter parameter (other than page) must be provided.

At least one of the following is required: purchaseCode, voucherCode, recipientEmail, isUsed, isActive, reservationCode, or storeExamCode. Providing only page returns a 400 Bad Request.

Request Headers

Header	Value	Required
Authorization	Bearer <token>	Required

Query Parameters

Parameter	Type	Required	Description
isActive	boolean	Conditional	Filter by active status.
isUsed	boolean	Conditional	true for used vouchers, false for unused.
page	integer	Optional	Page number. Defaults to 1.
purchaseCode	string	Conditional	Filter by associated purchase code.
recipientEmail	string	Conditional	Filter by assigned recipient email. Must be valid email format.
reservationCode	string	Conditional	Filter vouchers associated with a specific reservation code.
storeExamCode	string	Conditional	Filter vouchers linked to a specific store exam code.
voucherCode	string	Conditional	Filter by individual voucher code.

Response — 200 OKPartnerVoucherModel — data[]

Property	Type	Nullable	Description
assignedDateUtc	string (ISO 8601)	Nullable	Date/time assigned to recipient, UTC. Omitted if not assigned.
expirationDateUtc	string (ISO 8601)	No	Expiration date/time, UTC.
id	string	No	Unique identifier for the voucher.
isActive	boolean	No	Whether the voucher is eligible for use.
isUsed	boolean	No	Whether the voucher has been redeemed.
recipientEmail	string	Nullable	Assigned recipient email. Omitted if not assigned.
reservationCode	string	Nullable	Linked reservation code. Omitted if none.
reservationStatus	string	Nullable	Status of the associated reservation. Omitted if none.
storeExamCode	string	Nullable	Linked store exam code. Omitted if not linked.
usedBy	PartnerVoucherUsedByModel	Nullable	Redemption details. Omitted if not used.
voucherCode	string	No	Unique redemption code.
voucherPurchaseCode	string	No	Code identifying the purchase batch.

PartnerVoucherUsedByModel — usedBy (omitted when isUsed: false)

Property	Type	Description
clientCandidateId	string	Client-defined candidate identifier.
firstName	string	First name of the redeeming person.
lastName	string	Last name of the redeeming person.
personId	string	Identifier of the person who redeemed the voucher.
usedDateUtc	string (ISO 8601)	Date/time the voucher was redeemed, UTC.

HTTP Status Codes

Code	Description
200	Success.
400	Bad Request — no filter provided; invalid email; invalid boolean for isUsed/isActive.
401	Unauthorized.
422	Unprocessable Entity - Exceeded the 10,000 record limit
500	Internal Server Error.

 

Contact Us

If you have any questions or need additional assistance, please contact us by either emailing support@certiverse.com or by submitting a ticket from this article.