Administrator Knowledge Base

Integrations & APIs

Certiverse Eligibility API

Send candidate eligibility to test data to Certiverse

Certiverse Eligibility API

The Certiverse Eligibility API allows organizations to configure an exam in the Certiverse Exam Store to require eligibility, which is hosted by Certiverse, and sent to Certiverse using an API endpoint hosted by Certiverse. The eligibility data passed to Certiverse must include the candidate’s email and the exam store sku/exam code code. Organizations can optionally send a first name, last name, eligibility Id, candidate Id, date-time range the eligibility record is valid, and the date-time range the exam can be delivered. Organizations can create, update, delete and retrieve eligibility data in the Certiverse system using the API calls listed below. The candidate’s email address will be used to match eligibility to the candidate when booking the exam. If first name or last name are included in the eligibility those will be matched to the first and last name on the candidate account in Certiverse, in addition to the email address.

Creating Eligibility

The POST call is used to create new eligibility. The create eligibility call requires the candidate’s email address, and the exam code from the Certiverse Exam Store. The eligibility Id is optional, and if it is not included in the post call a system generated eligibility Id will be assigned and returned in the response. The eligibility Id must be used for subsequent calls to update, delete or retrieve the eligibility record. An eligibility Id can only be used to create an eligibility record one time for an organization. The eligibility Id cannot be reused even if the delete eligibility call is used.

Update Eligibility

Existing eligibility records can be updated using the PUT call. The eligibility Id is required to update eligibility and cannot be changed when updating eligibility. All other fields can be updated. The eligibility update will fail if the eligibility record has already been used, and has a pending, completed, or expired booking associated with the eligibility record. The eligibility record can be updated if it was used to create a booking and the booking is then canceled.

Delete Eligibility

Existing eligibility records can be updated using the DELETE call. The eligibility Id is required to delete an eligibility. Once deleted, and eligibility Id cannot be reused by an organization.

Search for Eligibility

Existing eligibility records can be retrieved using the GET call. The search for eligibility records can use either the eligibility Id, email address, or candidate Id. In addition to the eligibility data passed to Certiverse, booking data will be returned if the eligibility has been used to create a booking.

Booking Exams with Eligibility

Exams that are configured to use the Eligibility API will require an eligibility record that matches the users email address, the store exam code, and a valid date eligibility date range. If first name or last name were included in the eligibility record those must match the first and/or last name on the candidates Certiverse account. In cases where more than one valid eligibility record exists for a user and exam code, the record with the earliest eligibility end date, and will expire first, is used. If the eligibility records have the same end date, or no eligibility end date, the records will be used in the order they were created.

___________________________________________________________________________________________

Certiverse Eligibility API

Overview

Giving Organizations the ability to configure and exams in the Certiverse Exam Store to require eligibility which is passed to Certiverse using the API specifications below.

Version Information

Version: 1.1

URI Scheme

Base Path: /api

Scheme: HTTPS

Paths

Summary

Authenticate as a Certiverse partner to gain an authentication token for calls needing to be executed

GET /authenticate

Headers

Key

Description

Value

x-functions-key

API endpoint secret used for security

string: <value provided by Certiverse>

Authorization

Basic Auth

ClientId: String value provided by Certiverse

ClientSecret: String value provided by Certiverse

Query Parameters

Parameter	Description	Type
Code	Optional value to pass in that will be returned telling the caller API call has not been intercepted	string (optional)

Responses

Http StatusCode	Description	Schema
200	Return authentication token	PartnerDataTokensModel
400	Error if request is missing or invalid properties	ErrorModel
401	Error if credentials are incorrect	ErrorModel
500	Error if server errors	ErrorModel

Models

PartnerDataTokensModel (ContentType: application/json)

Property	Description	Type
authToken	Token for authorization on any other calls	string
code	Value provided in request returned	string

ErrorModel (ContentType: application/json)

Property	Description	Type
errorCode	Internal error code	string (optional)
errorMessages	List of error messages	string[]

Summary

Add user eligibility for an exam in the Certiverse Exam Store

POST /eligibility

Headers

Key	Description	Value
authorization	Authorization Bearer token	Bearer <token from authenticate call>

Parameters

Type	Description	Schema
Body	Command described with the following schema	CreateCommand

CreateCommand (ContentType: application/json)

Property	Description	Type
eligibilityId optional	Organizations unique identifier for eligibility record. Eligibility Id can only be used once Eligibility Id is used for updates and deletes of eligibility record If eligibilityId is not passed to Certiverse the unique identifier generated by Certiverse will be returned as the eligibilityId in the response and can be used for updates to the eligibility record	string
orgCandidateId optional	Candidate Id assigned by Organization or third party system Org Candidate Id is stored with the booking and exam delivery. The Org Candidate Id can be returned with results and is included in online results reports Org Candidate Id is separate from the User/Candidate Id assigned by Certiverse	string
firstName optional	Candidates first name. If the first name is include in eligibility record, it must match the account first name when the booking exam User will be notified if first name does not match when booking exam	string
lastName optional	Candidates last name If the last name is include in eligibility record, it must match the account first name when the booking exam User will be notified if last name does not match when booking exam	string
email required	Candidates email Used to match eligibility to user account	string
examCode required	Exam code/sku assigned to exam entry in the Certiverse exam store	string
eligibilityStartDateTime optional	Controls the start date-time time for when the eligibility record is valid and can be used to create a booking If omitted there is no start date-time restriction for the eligibility record Date-times in UTC Date Format 2023-10-01T00:00:00	datetime
eligibilityEndDateTime optional	Controls the end date-time time for when the eligibility record is valid and can be used to create a booking If omitted there is no end date-time restriction for the eligibility record Date-times in UTC Date Format 2023-10-01T00:00:00	datetime
deliveryStartDateTime optional	Controls the earliest appointment date-time for the exam store booking. If the exam is unscheduled, it will limit the start date-time for creating the booking If omitted there is no start date-time restriction for the booking appointment Date-times in UTC Date Format 2023-10-01T00:00:00	datetime
deliveryEndDateTime optional	Controls the latest appointment date-time for the exam store booking. If the exam is unscheduled, it will limit the end date-time for creating the booking If omitted there is no end date-time restriction for the booking appointment Date-times in UTC Date Format 2023-10-01T00:00:00	datetime

Responses

Http StatusCode	Description	Schema
200		EligibilityModel
400	Bad Request List of possible error descriptions in case of bad request Invalid Exam Code Eligibility Already exists Eligibility ID already exists for Org Invalid eligibility dates Invalid delivery dates	ErrorModel
401	Error if credentials are incorrect	ErrorModel
500	Error if server errors	ErrorModel

Models

EligibilityModel (ContentType: application/json)

Property	Description	Type
certiverseEligibilityId	System generated unique Id. Will be assigned to the eligibilityId if one was not included when creating eligibility.	string
eligibilityId		string
orgCandidateId	Not returned if null	string
firstName		string
lastName		string
email		string
examCode		string
eligibilityStartDateTime	Not returned if null	datetime
eligibilityEndDateTime	Not returned if null	datetime
deliveryStartDateTime	Not returned if null	datetime
deliveryEndDateTime	Not returned if null	datetime

ErrorModel (ContentType: application/json)

Property

Description

Type

errorCode

Internal error code

string (optional)

errorMessages

List of error messages

string[]

Summary

Update user eligibility for an exam in the Certiverse Exam Store

PUT /eligibility

Headers

Key	Description	Value
authorization	Authorization Bearer token	Bearer <token from authenticate call>

Parameters

Type	Description	Schema
Body	Command described with the following schema	UpdateCommand

UpdateCommand (ContentType: application/json)

Property	Description	Type
eligibilityId required	The Organization Eligibility Id used to create the eligibility record Must match an existing eligibility Id Eligibility must not have a pending, completed, or expired booking to be updated	string
orgCandidateId optional	If omitted will updated to null	string
firstName optional		string
lastName optional		string
email required		string
examCode required		string
eligibilityStartDateTime optional	If omitted will be updated to null	datetime
eligibilityEndDateTime optional	If omitted will be updated to null	datetime
deliveryStartDateTime optional	If omitted will be updated to null	datetime
deliveryEndDateTime optional	If omitted will be updated to null	datetime

Responses

Http StatusCode	Description	Schema
204
400	Bad Request List of possible error descriptions in case of bad request Eligibility Id not found Eligibility used to create a booking that is pending, completed or expired Invalid Exam Code Invalid eligibility dates Invalid delivery dates	ErrorModel
401	Error if credentials are incorrect	ErrorModel
500	Error if server errors	ErrorModel

Models

ErrorModel (ContentType: application/json)

Property	Description	Type
errorCode	Internal error code	string (optional)
errorMessages	List of error messages	string[]

Summary

Delete user eligibility for an exam in the Certiverse Exam Store

DELETE /eligibility

Headers

Key	Description	Value
authorization	Authorization Bearer token	Bearer <token from authenticate call>

Parameters

Type	Description	Schema
Body	Command described with the following schema	DeleteCommand

DeleteCommand (ContentType: application/json)

Property

Description

Type

eligibilityId required

The Organization Eligibility Id used to create the eligibility record

Must match an existing eligibility Id.
Eligibility must not have a pending, completed, or expired booking to be to be deleted

string

Responses

Http StatusCode	Description	Schema
204
400	Bad Request List of possible error descriptions in case of bad request Eligibility Id not found Eligibility used to create a booking that is pending, completed or expired.	ErrorModel
401	Error if credentials are incorrect	ErrorModel
500	Error if server errors	ErrorModel

Models

ErrorModel (ContentType: application/json)

Property	Description	Type
errorCode	Internal error code	string (optional)
errorMessages	List of error messages	string[]

Summary

Search for existing user eligibility for an exam in the Certiverse Exam Store

GET /eligibility

Headers

Key	Description	Value
authorization	Authorization Bearer token	Bearer <token from authenticate call>

Parameters

Type	Description	Parameter Name
Query string parameter	Only one query parameter per request	eligibilityId
Query string parameter	Only one query parameter per request	email
Query string parameter	Only one query parameter per request	candidateId

Responses

Http StatusCode	Description	Schema
200		EligibilitySearchResultsModel[]
400	Bad Request List of possible error descriptions in case of bad request Eligibility Id not found Email not found Candidate Id not found	ErrorModel
401	Error if credentials are incorrect	ErrorModel
500	Error if server errors	ErrorModel

Models

EligibilitySearchResultsModel (ContentType: application/json)

Property	Description	Type
data		EligibilityModel[]

EligibilityModel (ContentType: application/json)

Property	Description	Type
certiverseEligibilityId		string
eligibilityId		string
orgCandidateId		string
firstName		string
lastName		string
email		string
examCode		string
eligibilityStartDateTime	Not returned if null	datetime
eligibilityEndDateTime	Not returned if null	datetime
deliveryStartDateTime	Not returned if null	datetime
deliveryEndDateTime	Not returned if null	datetime
bookingCode	The booking code that is generated when a candidate books an exam using the eligibility record. Will not be included if a booking has not been created.	string
bookingStatus	The status of the booking created using the eligibility record. Will not be included if a booking has not been created. Booking Statuses Pending ExamInProgress Complete Expired Cancelled	string
bookingDateTime	The date-time the booking is scheduled to be delivered. If the booking is unscheduled, it will use the date-time it was created.	date

ErrorModel (ContentType: application/json)

Property	Description	Type
errorCode	Internal error code	string (optional)
errorMessages	List of error messages	string[]

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.