Search

Certiverse Voucher Partner API

Overview

The Certiverse Voucher Partner API provides read access to voucher partners, programs, purchases, and individual vouchers. All endpoints require a Bearer token associated with a user holding the PartnerManageVouchers function point.

All list endpoints support paginated responses. A nextLink property is included in the response when additional pages are available; when absent, the current page is the last.

Version: 1.0
Base Path: /api
Auth: Pattern B (Direct Bearer)
 

Voucher Partners

GET /api/vouchers/partners

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 
Complete
VoucherCreation
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 OK
PartnerVoucherModel — 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.

 

 

Updated

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.