Certiverse Promo Code API

Overview

The Certiverse Promo Code API allows partner organizations to create and retrieve promo codes that candidates can use to receive a discount when booking an exam in the Certiverse Exam Store.

Promo code names must be alphanumeric, unique within the organization, and between 3–25 characters. At least one store exam code must be specified. The status defaults to Inactive if not provided. If restrictToEmailAddresses is true, the emailAddresses field is required.

GET requests return results in pages of up to 100 records. If the total results exceed 10,000, the request returns an error and the query must be refined using filters.

Version: 1.0

Base Path: /api

Auth: Pattern A (Basic → Bearer)

GET /promo-codes

Retrieve existing promo codes for your organization. Without parameters, returns all promo codes (up to 10,000 records). Multiple filters may be combined. Results are paginated at up to 100 per page.

Request Headers

Key	Value	Required
`authorization`	`Bearer <token from authenticate>`	Required

Query Parameters

Parameter	Type	Required	Description
`emailAddress`	string	Optional	Filter to codes that include this email address in their restriction list. Can only be used when `restrictToEmailAddresses=true`
`page`	integer	Optional	Page number. Defaults to 1. Must be a positive integer.
`promoCodeName`	string	Optional	Filter by exact promo code name (case-insensitive).
`restrictToEmailAddresses`	string	Optional	Filter by email restriction flag: `true` or `false`.
`storeExamCode`	string	Optional	Filter by store exam code.
`status`	string	Optional	Filter by status: `Active`, `Inactive`, or `Archived`.

Response — 200 OK — PromoCodePagedResponseModel

Property	Type	Description
`data`	PromoCodeModel[]	Up to 100 promo codes per page.
`nextLink`	Link	Link to next set of results. `null` if no further results.

HTTP Status Codes

Code	Description
200	Success.
400	Bad Request — invalid `restrictToEmailAddresses` value; invalid `page`; invalid `status`; query returned too many results (refine using filters).
401	Unauthorized.
500	Internal Server Error.

POST /promo-codes

Create a new promo code for your organization.

Request Headers

Key	Value	Required
`authorization`	`Bearer <token from authenticate>`	Required

Request Body — CreateCommand

Property	Type	Required	Description
`storeExamCodes`	string[]	Required	List of store exam codes the promo code applies to. Must contain at least one exam.
`discountPercent`	integer (1–100)	Required	Percentage discount applied when the promo code is redeemed.
`expirationDateUtc`	datetime	Required	Expiry date. Cannot be in the past. UTC. Format: `2026-01-01T00:00:00`.
`maxRedemptions`	integer (1–100,000)	Required	Maximum total number of times the promo code can be redeemed.
`promoCodeName`	string	Required	Alphanumeric only. Unique within the organization. Length: 3–25 characters.
`emailAddresses`	string[]	Conditional	Required when `restrictToEmailAddresses` is `true`.
`isActive`	boolean	Optional	Defaults to `false`.
`maxRedemptionsPerCandidate`	integer (1–100,000)	Optional	Max redemptions per individual candidate. Cannot exceed `maxRedemptions`.
`notes`	string	Optional	Internal notes. Max 256 characters.
`restrictToEmailAddresses`	boolean	Optional	If `true`, only candidates in the `emailAddresses` list may redeem. Defaults to `false`.

Response — 201 Created — PromoCodeModel

Property	Type	Description
`storeExamCodes`	string[]
`discountPercent`	integer
`emailAddresses`	string[]
`expirationDateEndUtc`	datetime
`maxRedemptions`	integer
`maxRedemptionsPerCandidate`	integer	Not returned if null.
`notes`	string	Not returned if null.
`promoCodeName`	string
`redemptionCount`	integer	Times redeemed. Cancelled redemptions not counted.
`restrictToEmailAddresses`	boolean

HTTP Status Codes

Code	Description
201	Promo code created successfully.
400	Bad Request — name not alphanumeric; no exams provided; per-candidate limit exceeds max; expiry in past; invalid status; emailAddresses missing when restricted; exam codes not found; duplicate promo code name.
401	Unauthorized.
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.