Introduction Last updated: 2024-02-01

This documentation describes how to use our ISO Certificate API. The API is protected from unauthorized use by restricting calls to those that provide proper authentication credentials. The credentials must be provided in the form of an API key. The API Key is a unique alphanumeric string associated to your pusrchased order of one of our avalaible licences.

The number of calls to the API will be limited to a maximum number depending on the license purchased. However, there are no time limits.

Where are my API keys?

You can view and track your API keys with the remaining credits in your Account details, Orders Dashborad. Your API Key can be copied from the Order details viewer.

How to use my API keys?

The ISO Certificate is organized around HTTP REST. It accepts JSON-encoded request bodies and returns JSON-encoded responses, and uses standard HTTP response codes. To authenticate your HTTPS requests, our service uses the API keys. Each call request to our service must include a valid API key in the specific HTTP header named X-CSTN-Services-API-Key

API Usage

This section describes how to send requests to our ISO Certificate API with Curl and PHP.

API Endpoint

The ISO Certificate API can be accessed using the following endpoint:

https://apinxs.costeny.com:5003

Request description

The API accepts as input an ISO certificate document in PDF format and a given company name. The service extracts one or several ISO certificates. For each certificate, a set of properties are extracted (ISO name, issue date, expire date, etc.) in addition to a validity score (0 to 100). The API accepts only text based PDF documents.

Request parameters

Name	Description	Required
content	PDF content encoded in Base64	Yes
company	The company registred in the certificate	No

In the rest of this documentation, each reference to YOUR-API-KEY must be replaced with your API Key value.

Curl request

curl -X POST https://apinxs.costeny.com:5003
	-H 'Content-Type: application/json'
	-H 'X-CSTN-Services-API-Key: YOUR-API-KEY'
	-d '{
		"data" : {
			"content" : "pdf_content_in_base64",
			"company": "the_certificate_company_name"
			}
		}'

PHP request

// Set parameters
$post_fields = array(
	"data" => array(
		"company" : "the_certificate_company_name",
		"content" : "pdf_content_in_base64"
	)
);
// Send request
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-CSTN-Services-API-Key: {$YOUR-API-KEY}"]);
curl_setopt($ch, CURLOPT_URL, "https://apinxs.costeny.com");
curl_setopt($ch, CURLOPT_PORT, 5003);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_fields));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Response description

The response is JSON encoded. Herein an example of a response for a PDF document including several certificates.

{
	"certificates": [
		{
			"iso": "ISO 9001:2015",
			"language": "english",
			"issue_date": "2022-11-06",
			"expire_date": "2025-11-05",
			"validity.score": 40
		},
		{
			"iso": "ISO 14001:2015",
			"language": "english",
			"issue_date": "2022-11-06",
			"expire_date": "2025-11-05",
			"validity.score": 40
		}
	]
}

Response fields

Name	Description	Always available ?
iso	Certificate name	Yes
language	The certificate content language (english, french, german, italian, spanish, portuguese)	Yes
issue_date	The extracted certificate issue date	Yes
expire_date	The extracted certificate expire date	No
first_date	The extracted original issue date	No
validity.score	Measure of the certificate validity: 0 (highly suspect) to 100 (fully validated).	Yes

Errors

In case of fail, the service returns an error in JSON format.

{
  "error": "No extracted certificate"
}

Error messages

Message	Status Code
Missing Api key header	403
Invalid API key	403
Forbidden Access for the API key	403
Rate limit reached for the API key	403
Invalid input data	200
An exception occurs during processing	200
Reading content failed	200
Empty content (probably image based PDF)	200
Content processing error	200
No extracted certificate	200

FAQs

Frequently asked questions.

The demo tool keeps returning an error with company name.

Make sure to register with the correct Company name.
This field will be the one compared with the name on the ISO certificate you will upload to test.