Integrating a Certificate Verification Tool into Your Website
Overview
To maximize the chain of trust around the validity of the certificates you issue, you can integrate an online certificate verification tool into your institutional website. A dedicated endpoint and source code example are provided to make this integration as straightforward as possible.
Verification API
The verification feature is accessible via a POST request to the following endpoint: [API-URL]/v2/verifier.
Required HTTP header: Content-Type: application/json
The request body must be a valid JSON object with the following structure:
- issuer: your issuer ID (integer), or an array of IDs if you have multiple (e.g.
253or[2, 253]) - url: the full URL of the certificate to verify
{
"issuer": integer | [integer, ...],
"url": "string"
}
Request body example:
{
"issuer": [2, 253],
"url":"https://www.leaston.org/certificates/certificate.html?env=prod&key=756CF1818595DBED0045749D10DA231CE9BE48E67288B1553598F5F8D848C389cFZuL1JmT1EvOG5ZY09LM3c0YXprY2ZTMXRaeURvU3NpZk8vUW5oN00zWTVKVkpX"
}
Response
The /v2/verifier endpoint returns a JSON object containing a response code, a response message, and all public fields from the certificate, along with the appropriate HTTP status code. Response codes are indicated in parentheses before the text message (e.g., (IS_OK) Url is valid).
Response example:
{
"code": "IS_OK",
"message": "Url is valid",
"templateId": "1x0C",
"templateLabel": {
"en": "Strategic Artificial Intelligence for Business Applications",
"fr": "Intelligence Artificielle Stratégique pour les Applications Business"
},
"data": {
"ID": "1",
"Email": "support@bcdiploma.com",
"firstName": "Jane",
"lastName": "Doe",
"obtentionDate": "2025-10-02",
"ExpirationDate": "2125-01-03",
"assessment": "",
"linkLabel": "",
"linkURL": ""
},
"attributedTo": "Jane Doe"
}
Success (HTTP Status Code: 200)
The URL is recognized as authentic and as having been issued through BCdiploma. However, the certificate may be in a state that makes it temporarily or permanently inaccessible. This state is detailed in the text message associated with the return code.
IS_OK Url is valid
IS_EXPIRED Url is valid but certificate has expired
IS_DISABLED Url is valid but certificate has been disabled
IS_DELETED Url is valid but certificate has been subject to the right of oblivion
NON_VERIFIED_ISSUER Url is valid, but the certificate's issuer has not been verified yet
Failures
HTTP Status Code: 400
INVALID_URL Given url is invalid
NO_KEY_IN_URL Given url does not contain key
HTTP Status Code: 403
UNAUTHORIZED_DOMAIN Domain is invalid
INCORRECT_ISSUER Url is valid but not issued by given issuer
HTTP Status Code: 404
UNKNOWN_KEY The key is unknown
Usage Example
cURL Example
curl -X POST https://api.bcdiploma.com/v2/verifier \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.leaston.org/certificates/certificate.html?env=prod&key=756CF1818595DBED0045749D10DA231CE9BE48E67288B1553598F5F8D848C389cFZuL1JmT1EvOG5ZY09LM3c0YXprY2ZTMXRaeURvU3NpZk8vUW5oN00zWTVKVkpX",
"issuer": 253
}'
Algorithm
- The validity of the provided URL is checked. If the URL is not a valid URL, then error 400.
- The key is extracted from the URL (search for the pattern
\b[a-zA-Z0-9]{128}\b). If no key is found, then error 400. - The existence of the key in our registry is checked. If the key is not found, then error 404.
- The domain of the provided URL is verified against the different possibilities (bcdiploma.com, evidenz.io, 3videnz.com, or the issuer domain as defined in the template). If the domain is not valid, then error 403.
- If the issuer is specified in the request, it is compared to the actual issuer of the document. If it differs from the actual issuer of the certificate, then error 403.
- The status of the document is checked. At this point the return code is 200, but the message may vary depending on the document status.
- If the verification is successful, all public fields from the certificate are returned along with the return code and message.
Website Integration Example
This basic example consists of 3 files. Copy the contents below into 3 files in a directory of your choice to test it.
- An HTML file
index.htmlcontaining the structure of the verification page
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BCdiploma Verifier</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>
<main>
<div class="container">
<input type="text" id="inputField" placeholder="Copy the URL to verify">
<button id="submitButton">Verify</button>
<div id="result"></div>
</div>
</main>
<script src="script.js"></script>
</body>
</html>
- A JavaScript file
script.jscontaining the API call
// Override this map to customize messages displayed for each return code.
const VERIFIER_MESSAGES = {
IS_OK: null, // null = use the message from the API response
IS_EXPIRED: null,
IS_DISABLED: null,
IS_DELETED: null,
NON_VERIFIED_ISSUER: null,
INVALID_URL: null,
NO_KEY_IN_URL: null,
UNKNOWN_KEY: null,
UNAUTHORIZED_DOMAIN: null,
INCORRECT_ISSUER: null,
};
function getDisplayMessage(responseBody) {
const customMessage = VERIFIER_MESSAGES[responseBody.code];
return customMessage !== null && customMessage !== undefined
? customMessage
: responseBody.message;
}
document.getElementById('submitButton').addEventListener('click', function() {
var inputValue = document.getElementById('inputField').value;
fetch('https://api.bcdiploma.com/v2/verifier', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({url: inputValue, issuer: 253}) // Replace this value with your own issuer ID
})
.then(response => response.json())
.then(data => {
var resultDiv = document.getElementById('result');
resultDiv.textContent = getDisplayMessage(data);
})
.catch(error => console.error('Error :', error));
});
- A stylesheet for layout and styling.
body {
font-family: Arial, sans-serif;
margin: 0;
padding: 0;
}
header {
background-color: #2E3B4E;
padding: 20px;
text-align: center;
}
header img {
max-width: 100%;
}
main {
display: flex;
justify-content: center;
align-items: center;
height: 100vh;
background-color: #F6F8F9;
}
.container {
text-align: center;
}
input {
padding: 10px;
margin-right: 10px;
border: 1px solid #ccc;
border-radius: 4px;
font-size: 16px;
}
button {
padding: 10px 20px;
background-color: #2E3B4E;
color: #fff;
border: none;
border-radius: 4px;
font-size: 16px;
cursor: pointer;
}
button:hover {
background-color: #1E2736;
}
FAQ
I receive an error saying the certificate is invalid even though it exists in BCdiploma
If the API response returns the code INCORRECT_ISSUER (HTTP 403), it means the certificate URL is valid but was not issued by the issuer specified in your API call.
Make sure the issuer parameter matches your issuer ID in BCdiploma. This ID is available in the Administration section of your BCdiploma back office. Replace the value used in the example (253) with your own issuer ID.
How do I customize the messages displayed to the user?
The messages returned by the API can be overridden with your own. To adapt them to your editorial guidelines, edit the VERIFIER_MESSAGES map in script.js. Replace the null value for a given code with the message of your choice: if the value is null, the default message from the API is displayed; otherwise, your custom message is used.
How do I test the integration on the staging environment?
To point to the BCdiploma staging environment, replace the API URL in script.js:
fetch('https://api-staging.bcdiploma.com/v2/verifier', {
instead of:
fetch('https://api.bcdiploma.com/v2/verifier', {