NAV
cURL Python

Introduction

Welcome to the VDX Core API, or Core API for short. The Core API is a REST API that provides developers with a simple-to-use interface to several Blockchains for the purpose of issuing Blockchain verifiable credentials. If you already have an existing solution in place, and would like to plug in Blockchain functionality, the Core API is what you need.

In a very summarized flow, you only need to upload your files to the Core API, create a Credential with it, by adding any additional metadata, and issue it onto the Blockchain of your choice. After it has been fully issued and confirmed, the credential is perpetually and irrevocably verifiable.

Every endpoint available on the Core API is described and accompanied by a visual example of how the API responds. For an improved experience when integrating the Core API to your code, you can import our libraries:

All Python examples used in the examples are from the above library.

The Core API is available in two different environments - the "Demo" and the "Live" environments. The former can be used for free testing, since it is connected to the Testnet Blockchain and does not affect your live data. There is also no limits to the number of requests, however any documents issued through the "Demo" environment have no validity. The "Live" environment is connected to the Mainnet Blockchains, so its use is limited per the subscribed tier or your contract with Vizidox.

For further information on each endpoint, feel free to consult the Core API Swagger UI page, which can also be used to test these endpoints on the Demo environment.

Please check our Privacy Policy for more details on data collection. Furthermore, by using the Core API you are agreeing to our Terms and Conditions.

Endpoint URLs

All endpoints and parameters are the same between both available environments. Although the examples provided in the documentation display the Live environment URL, you just need to switch the domain if you want to use the Demo environment instead.

The API Key used for authentication on each environment is different as well.

Environment URL
Live https://vizidox.com/api
Demo https://api-demo.vizidox.com/api

Pagination

class PaginatedView(NamedTuple):
    page: int
    total_pages: int
    per_page: int
    total_items: int
    items: List[Object]

JSON Response

{
  "page": 1,
  "total_pages": 1,
  "per_page": 20,
  "total_items": 2,
  "items": [{}]
}

Most of the provided API resources have support for bulk retrievals, such as the "Get All Files" endpoint. The result for these endpoints is always paginated, and they contain common query parameters for managing the pagination.

All of these parameters are fully optional and default values are applied when they are not provided in the request.

Parameter Description Default
sort_by Field to sort the results by. Value is specific to the endpoint Endpoint specific
order Order, ascending or descending, according to the sorty_by parameter asc
per_page Number of results per page. 0 for all results in one page 20
page Page number to request 1

Errors

All paginated endpoints return a specific error if any given pagination argument is incorrect:

id code Description
wrong_pagination_argument 422 Invalid argument used for pagination

Tags

The Core API allows the use of tags to further help with filtering and searching for credentials, jobs and certificates. These tags can be added to credentials or jobs, and can then be used to search for all credentials or jobs that contain those specific tags, or certificates created from credentials or issued on jobs with specific tags.

All tags have a format that must be followed:

Tags can be directly added to credentials when creating them, or after creation through specific endpoints that are detailed below. Although you cannot add tags to Jobs on creation, they can be added afterward in the same way as credentials.

On retrieval endpoints, tags can be used as query parameters to filter the results. The parameters that can be used are:

Name Type Optional Description
and_tags Query Yes Obtain objects that contain all the listed tags. Format is "and_tags=tagA,tagB"
or_tags Query Yes Obtain objects that contain at least one of the listed tags. Format is "or_tags=tagA,tagB"

Authentication

curl -H "Content-Type: application/json" \ 
     -d '{"grant_type":"client_credentials","client_secret":"<API_KEY>}","client_id":"<CLIENT_ID>"}' \
     https://vizidox.com/auth/realms/core-api/protocol/openid-connect/token
curl https://vizidox.com/api/<ENDPOINT> \
     -H "Authorization: Bearer <TOKEN>"
from vdx_helper import VDXHelper

vdx_helper = VDXHelper(url="https://vizidox.com/api", 
                       keycloak_url=https://vizidox.com/auth/realms/core-api/protocol/openid-connect/token,
                       core_api_key=<API_KEY>, core_api_client_id=<CLIENT_ID>)

Make sure to replace <API_KEY> with your API key and <CLIENT_ID> with your Client ID

The VDX Core API uses API Keys to authenticate requests, through the OAuth 2.0 Client Credentials grant. The API Key is provided to you directly, or through your team settings on the VDXapi Portal.

All API requests need to be made over HTTPS and with valid authentication.

First, use your API Key to request an authorization token from our authentication server. Afterward, use that token in any API request.

You should not share your Key with any unauthorized third party, nor post it in any public area such as a repository.

Issuing with Vizidox

With the Vizidox Core API, you can choose to either issue a file, metadata in json format, or both at the same time. A single credential can also be issued with multiple files attached to it as well. Furthermore, the credentials that are created on the system (which contain these files and metadata) can also be linked to one another, creating a Credential Record. This means that you can keep adding new credentials to this Record, updating the data without being able to edit old entries, and these are all linked together.

To issue credentials, the Vizidox API works on a scheduling basis. Instead of manually starting the issuing process when you register a credential on the system, you simply mark these credentials to be issued on a specific Blockchain. All scheduled credentials are issued at the same time when the next issuing date for your partner is. The frequency in issuings is either defined by you when you manage your partner settings on the VDXapi Portal, or directly with Vizidox depending on your contract.

To issue data to the Blockchain, there are three important steps:

Each of the endpoints required for these steps are explained in more detail in the Resources section.

Resources

Response

{
  "result": {},
  "meta": {
    "last_update": "Mon, 18 Apr 2022 15:05:00 GMT",
    "date": "Thu, 21 Apr 2022 15:17:27 GMT",
    "message": ":)",
    "version": "2022.04.1",
    "documentation": "https://docs.vizidox.com"
  }
}

All endpoints in the Core API follow a specific format which contains the results itself of the endpoint, as well as an extra field for server information. This field is called "meta", and it contains:

Partner

{
  "id": "vizidox",
  "name": "Vizidox"
}

A Partner represents the client sending requests to the Core API. All credentials that are issued by you are associated to your partner ID, and your API Key will only work with the correct partner ID as well.

File

The File Object

{
  "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
  "file_type": "image/jpeg"
}

The File object represents a file uploaded to Vizidox by a Partner. It contains two fields:

Field Description
file_hash The hash of the file
file_type The MIME type of the file

The file_type parameter has to follow the MIME standard.

Upload File

curl -X POST "https://vizidox.com/api/files" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf" -F "ignore_duplicated=true"
file = vdx_helper.upload_file(file_stream, ignore_duplicated, mapper)
class FileView(NamedTuple):
    file_hash: str
    file_type: Optional[str]

Uploads a file to the Core API, and stores its hash for future issuing. This endpoint will not trigger the issuing process for the uploaded file.

Parameter Type Optional Description
file Form Data No The file to be uploaded
ignore_duplicated Form Data Yes Set to true to upload even if the file has already been uploaded in the past. Default is false.

It should be noted that if a file is not used to create a credential, it is automatically deleted from the server after one hour.

HTTP Request

POST https://vizidox.com/api/files

Returns

If successful, the HTTP response is a 201 CREATED, along with a file object.

Errors

id code Description
no_file_on_payload 400 Missing the file in the request
file_already_exists 409 File has already been uploaded

Get All Files

curl -X GET "https://vizidox.com/api/files" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
file = vdx_helper.get_files(mapper, file_hash, pagination)
class PaginatedView(NamedTuple):
    page: int
    total_pages: int
    per_page: int
    total_items: int
    items: List[FileView]

Obtain all files uploaded by the Partner. Includes the pagination arguments.

Parameter Type Optional Description
file_hash Query Yes Specific file hash to search for

HTTP Request

GET https://vizidox.com/api/files

Pagination

sort_by parameter can be filled in with:

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of files.

Get A File

curl -X GET "https://vizidox.com/api/files/<HASH>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>
file = vdx_helper.get_file_attributes(file_hash, mapper)

Obtains a specific file

Parameter Type Optional Description
file_hash Path No File hash to obtain

HTTP Request

GET https://vizidox.com/api/files/<HASH>

Returns

If successful, the HTTP response is a 200 OK, along with a file object

Errors

id code Description
missing_file 404 The file was not found

Credential

The Credential Object

{
      "uid": "123e4567-e89b-12d3-a456-426655440000",
      "title": "Credential Title",
      "metadata": {"Name":  "Special Credential"},
      "files": [
        {
          "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
          "file_type": "image/jpeg"
        }
      ],
      "credentials": [
        {
          "uid": "123e4567-e89b-12d3-a456-426655440000",
          "title": "Different Credential Title",
          "metadata": {},
          "files": [
            {
              "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
              "file_type": "application/pdf"
            }
          ],
          "credentials": [{}],
          "upload_date": "2020-01-11T15:34:05.811954+00:00",
          "tags": [
            "tagA"
          ]
        }
      ],
      "upload_date": "2020-02-11T15:34:05.811954+00:00",
      "tags": [
        "tagA",
        "tagB"
      ],
      "expiry_date": "2025-02-11T15:34:05.813229+00:00"
}

Fingerprint of the file, including additional data provided by the Partner. Optionally, can only contain metadata without a file.

Field Description
uid The unique identifier of the credential
title The title of the credential
metadata Additional metadata for the credential
files Files associated with the credential
credentials Other credentials associated with the credential
upload_date Date of credential upload
tags Tags to identify the credential
expiry_date Date the credential expires, if applicable

Create Credential

curl -X POST "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: application/json" -d "{  \"title\": \"Example Title\",  \"metadata\": {\"Name\": \"Example\"}, \ 
  \"files\": [\"056f32ee5cf49404607e368bd8d3f2af\"],  \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"],  \
  \"tags\": [\"TagA\"],  \"expiry_date\": \"2020-02-11T15:34:05.814607+00:00\"}"
credential = vdx_helper.create_credential(title, metadata, tags, file_hashes, credential_uids, expiry_date, mapper)
class CredentialView(NamedTuple):
    uid: UUID
    title: str
    metadata: dict
    files: List[FileView]
    credentials: List['CredentialView']
    upload_date: datetime
    tags: List[str]
    expiry_date: Optional[datetime]

Credential Creation Request Body

{
  "title": "Example Credential",
  "metadata": {"Name": "Example"},
  "files": ["5d6abece8532c71bb51a749a6af06de7"],
  "credentials": ["123e4567-e89b-12d3-a456-426655440000"],
  "tags": ["tagA"],
  "expiry_date": "2030-01-01T15:34:05.814607+00:00"
}

Creates a credential on the Core API, either from a file or from metadata. This endpoint will not trigger the issuing process for the created credential. If no file is provided, the metadata dictionary can not be empty.

Parameter Optional Description
title No The title of the credential
metadata No Additional metadata for the credential. Can be empty if file is provided
files Yes List of one or more file hashes to associate the credential with
credentials Yes List of one or more credential UIDs to associate the credential to
tags Yes Tags for identifying the credential
expiry_date Yes Date of expiry of the credential

HTTP Request

POST https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 201 CREATED, along with a credential object.

Errors

id code Description
missing_file_and_metadata 400 Either missing a file or metadata in the request
invalid_value 400 Invalid value in the request
missing_file 404 One or more of the given files cannot be found
no_json 415 Missing parameter in the request body
missing_field 422 Missing a field in the request body

Create and Schedule Credential

curl -X POST "https://vizidox.com/api/credentials/schedule/<engine>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf" \
  -F "credential_details={\"title\": \"Example Title\", \"metadata\": {\"Name\": \"Example\"}, \ 
  \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"], \"tags\": [\"TagA\"], \
  \"expiry_date\": \"2029-02-11T15:34:05.814607+00:00\", \"ignore_duplicate\": \"true\"}"

Credential Schedule Request Body

{
  "title": "Example Credential",
  "metadata": {"Name": "Example"},
  "credentials": ["123e4567-e89b-12d3-a456-426655440000"],
  "tags": ["tagA"],
  "expiry_date": "2030-01-01T15:34:05.814607+00:00",
  "ignore_duplicate": "true"
}

Creates a new credential on the Core API, either from a file uploaded directly on the same request, or from the provided metadata. After the credential is created, it is automatically scheduled for issuing on the provided engine. This endpoint will not trigger the issuing process for the created credential. If no file is provided, the metadata dictionary can not be empty.

Parameter Type Optional Description
engine Path No The engine to schedule the created credential
file Form Data Yes The file to issue, optionally
title Form Data No The title of the credential
metadata Form Data No Additional metadata for the credential. Can be empty if file is provided
credentials Form Data Yes List of one or more credential UIDs to associate the credential to
tags Form Data Yes Tags for identifying the credential
expiry_date Form Data Yes Date of expiry of the credential
ignore_duplicate Form Data Yes Set to true to upload even if the file has already been uploaded in the past. Default is false.

HTTP Request

POST https://vizidox.com/api/credentials/schedule/<engine>

Returns

If successful, the HTTP response is a 201 CREATED, along with a Job object.

Errors

id code Description
missing_file_and_metadata 400 Either missing a file or metadata in the request
invalid_tag 400 At least one tag has an invalid value
duplicated_tags 400 The provided tags contain duplicate values
invalid_expiry_date 400 The expiry date is invalid
missing_job 404 One or more of the given files cannot be found
file_already_exists 409 The file has already been uploaded
no_json 415 Missing parameter in the request body
missing_field 422 Missing a field in the request body
wrong_blockchain_engine 422 The provided blockchain engine is invalid

Get All Credentials

curl -X GET "https://vizidox.com/api/credentials" -H  "accept: application/json" -H "authorization: Bearer <TOKEN>"
credentials = vdx_helper.get_credentials(mapper, metadata, uid, start_date, 
                                         end_date, and_tags, or_tags, pagination)

Obtains all credentials previously created by the Partner. Includes the pagination arguments.

Parameter Type Optional Description
uid Query Yes Specific Credential UID to search for
upload_date_from Query Yes Obtain Credentials created after this date
upload_date_to Query Yes Obtain Credentials created up to this date
and_tags Query Yes Obtain Credentials that contain all the listed tags. Format is "and_tags=tagA,tagB"
or_tags Query Yes Obtain Credentials that contain at least one of the listed tags. Format is "or_tags=tagA,tagB"

HTTP Request

GET https://vizidox.com/api/credentials

Pagination

sort_by parameter can be filled in with (Default is created_date):

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of credentials.

Get A Credential

curl -X GET "https://vizidox.com/api/credentials/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
credential = vdx_helper.get_credential(cred_uid, mapper)

Obtains a specific credential

Parameter Type Optional Description
cred_uid Path No Credential UID to obtain

HTTP Request

GET https://vizidox.com/api/credentials/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with a credential object

Errors

id code Description
missing_credential 404 The credential was not found

Add Tags

curl -X PATCH "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
          -H  "Content-Type: application/json" -d "{\"credentials\": [{\"credential_uid\": \"123e4567-e89b-12d3-a456-426655440000\", \
               \"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"
updated_tags = {"credentials": [{"credential_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.update_credential_tags(updated_tags)

Tag Addition Request Body

{
  "credentials": [
    {
      "credential_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "credential_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Add new tags to a credential. This endpoint can be used to update more than one credential, by providing a list in the correct format on the body of the request.

Old tags will not be deleted.

HTTP Request

PATCH https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

id code Description
invalid_tag 400 At least one tag is in an incorrect format
duplicated_tags 400 At least one tag is repeated in the request
missing_credential 404 One or more credentials were not found

Replace Tags

curl -X PUT "https://vizidox.com/api/credentials" -H  "accept: application/json" -H  "Content-Type: application/json" \
             -H  "authorization: Bearer <TOKEN>" \
             -d "{  \"credentials\": [{\"credential_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"
new_tags = {"credentials": [{"credential_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.replace_credential_tags(new_tags)

Tag Replacement Request Body

{
  "credentials": [
    {
      "credential_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "credential_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Replace all the tags in a credential. This endpoint can be used to update more than one credential, by providing a list in the correct format on the body of the request.

Old tags are all deleted.

HTTP Request

PUT https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

id code Description
invalid_tag 400 At least one tag is in an incorrect format
duplicated_tags 400 At least one tag is repeated in the request
missing_job 404 One or more jobs were not found

Delete Credential Tags

curl -X PATCH "https://core-dev.vizidox.com/api/credentials/<UID>/delete_tag?tag=<TAG>>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
vdx_helper.delete_credential_tag(credential_uid, tag)

Deletes the tag from the given credential.

Parameter Type Optional Description
uid Path No UID of the credential to update
tag query No Tag to be deleted from the credential

HTTP Request

PUT https://vizidox.com/api/credentials

Returns

If successful, the HTTP response is a 200 OK with no additional content

Errors

id code Description
tag_does_not_exist 404 Tag does not exist in the credential
missing_credential 404 Credential was not found

Schedule Credentials

curl -X POST "https://vizidox.com/api/credentials/schedule" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
             -H  "Content-Type: application/json" -d "{\"engine\": \"bitcoin\", \"credentials\": [\"123e4567-e89b-12d3-a456-426655440000\"]}"
job = vdx_helper.schedule_credentials(engine, credentials, mapper)

Credential Schedule Request Body

{
  "engine": "bitcoin",
  "credentials": [
    "123e4567-e89b-12d3-a456-426655440000",
    "ce8bd4a4-e011-43ca-b775-d9569c690c42"
  ]
}

Schedules one or more existing credentials on the Core API. The given credentials will be added to the current scheduled job, to be issued at the next issuing schedule.

A Credential cannot be issued more than once on the same Blockchain Engine, however it can be issued over multiple engines.

Parameter Optional Description
engine No Blockchain engine to schedule the credentials on
credentials No List of credentials to schedule

HTTP Request

POST https://vizidox.com/api/credentials/schedule

Returns

If successful, the HTTP response is a 201 CREATED, along with a job object.

Errors

id code Description
missing_credential 404 One or more of the credentials cannot be found
credential_already_scheduled_or_issued 409 One or more of the credentials have already been scheduled or issued
no_json 415 Missing the request body
wrong_blockchain_engine 422 Given engine is incorrect or invalid
missing_field 422 Missing a field in the request body

Unschedule Credential

curl -X DELETE "https://vizidox.com/api/credentials/<UID>/unschedule/<engine>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
job = vdx_helper.schedule_credentials(engine, credentials, mapper)

Unschedules an existing (and previously scheduled) Credential from the given Blockchain engine. If the Credential is not scheduled nor issued on any other Blockchain engine, then it is also deleted.

Parameter Optional Description
cred_uid No UID of the credential to unschedule
engine No Blockchain engine the credential is scheduled on

HTTP Request

DELETE https://vizidox.com/api/credentials/<UID>/unschedule/<engine>

Returns

If successful, the HTTP response is a 200 OK.

Errors

id code Description
missing_credential 404 The Credential cannot be found
missing_job 404 There is no scheduled Job for the given engine
credential_not_scheduled 409 The Credential is not scheduled on the given engine
wrong_blockchain_engine 422 Given engine is incorrect or invalid

Job

The Job Object

{
  "uid": "123e4567-e89b-12d3-a456-426655440000",
  "partner": {
    "id": "vizidox",
    "name": "Vizidox"
  },
  "chain": "bitcoin",
  "tags": ["tagA"],
  "status": "finished",
  "start_date": "2020-02-11T15:34:05.814703+00:00",
  "issued_date": "2020-02-11T15:34:08.814719+00:00",
  "finished_date": "2020-02-11T15:38:05.814731+00:00",
  "failed_date": null,
  "created_date": "2020-02-10T18:34:05.814743+00:00",
  "scheduled_date": null
}

A Job is a Blockchain transaction containing a bundle of credentials. A job has several status:

Get All Jobs

curl -X GET "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
# start_date and end_date will be used on the issued_date_from and issued_date_until parameters
jobs = vdx_helper.get_jobs(mapper, job_status, uid, start_date, end_date, and_tags, or_tags, pagination)

Obtains all the Partner's jobs. Includes the pagination arguments and tags to filter by.

Parameter Type Optional Description
uid Query Yes Specific Credential UID to search for
status Query Yes Search for jobs in given status
start_date_from Query Yes Obtain Jobs that started issuing after this date
start_date_until Query Yes Obtain Jobs that started issuing up to this date
issued_date_from Query Yes Obtain Jobs that finished issuing after this date
issued_date_until Query Yes Obtain Jobs that finished issuing up to this date
created_date_from Query Yes Obtain Jobs created after this date
created_date_until Query Yes Obtain Jobs created up to this date

HTTP Request

GET https://vizidox.com/api/jobs

Pagination

sort_by parameter can be filled in with (default is created_date):

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of jobs.

Get A Job

curl -X GET "https://vizidox.com/api/jobs/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
job = vdx_helper.get_job(job_uid, mapper)

Obtains a specific Job

Parameter Type Optional Description
job_uid Path No Job UID to obtain

HTTP Request

GET https://vizidox.com/api/jobs/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with a job object.

Errors

id code Description
missing_job 404 The job was not found

Add Tags

curl -X PATCH "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
              -H  "Content-Type: application/json" \
              -d "{\"jobs\": [{\"job_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}  ]}"
updated_tags = {"jobs": [{"job_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.update_job_tags(updated_tags)

Tag Addition Request Body

{
  "jobs": [
    {
      "job_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "job_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Add new tags to a job. This endpoint can be used to update more than one job, by providing a list in the correct format on the body of the request.

Old tags will not be deleted.

HTTP Request

PATCH https://vizidox.com/api/jobs

Returns

If successful, the HTTP response is a 200 OK with no additional content.

Errors

id code Description
invalid_tag 400 At least one tag is in an incorrect format
duplicated_tags 400 At least one tag is repeated in the request
missing_job 404 One or more jobs were not found

Replace Tags

curl -X PUT "https://vizidox.com/api/jobs" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
            -H  "Content-Type: application/json" \
            -d "{\"jobs\": [{\"job_uid\": \"123e4567-e89b-12d3-a456-426655440000\",\"tags\": [\"tagA\",\"tagB\",\"tagC\"]}]}"
new_tags = {"jobs": [{"job_uid": "123e4567-e89b-12d3-a456-426655440000","tags": ["tagA", "tagB", "tagC"]}]}
vdx_helper.replace_job_tags(new_tags)

Tag Replacement Request Body

{
  "jobs": [
    {
      "job_uid": "123e4567-e89b-12d3-a456-426655440000",
      "tags": ["tagA", "tagB", "tagC"]
    },
    {
      "job_uid": "ce8bd4a4-e011-43ca-b775-d9569c690c42",
      "tags": ["tagA", "tagD"]
    }
  ]
}

Replace all the tags in a job. This endpoint can be used to update more than one job, by providing a list in the correct format on the body of the request.

Old tags are all deleted.

HTTP Request

PUT https://vizidox.com/api/jobs

Returns

If successful, the HTTP response is a 200 OK with no additional content.

Errors

id code Description
invalid_tag 400 At least one tag is in an incorrect format
duplicated_tags 400 At least one tag is repeated in the request
missing_job 404 One or more jobs were not found

Get Credentials in Job

curl -X GET "https://vizidox.com/api/jobs/<UID>/credentials" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
credentials = vdx_helper.get_job_credentials(job_uid, and_tags, or_tags, mapper, pagination)

Obtains all credentials issued in a specific job. Includes the pagination arguments.

Parameter Type Optional Description
job_uid Path No Job UID to obtain the credentials

HTTP Request

GET https://vizidox.com/api/jobs/<UID>/credentials

Pagination

sort_by parameter can be filled in with (Default is created_date):

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of credentials.

Get Certificates in Job

curl -X GET "https://vizidox.com/api/jobs/<UID>/certificates" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
certificates = vdx_helper.get_job_certificates(job_uid, and_tags, or_tags, mapper, pagination)

Obtains all certificates issued in a specific job. Includes the pagination arguments.

Parameter Type Optional Description
job_uid Path No Job UID to obtain the certificates

HTTP Request

GET https://vizidox.com/api/jobs/<UID>/certificates

Pagination

sort_by parameter can be filled in with (Default is issued_date):

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of certificates.

Issue Job

curl -X POST "https://api-demo.vizidox.com/api/jobs/immediate" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>" \
  -H  "Content-Type: application/json" -d "{  \"engine\": \"bitcoin\"}"

Issue Job Request Body

{
  "engine": "bitcoin"
}

Triggers the issuing process immediately on a certain blockchain engine. All the scheduled credentials for that engine will be issued. Only available on the demo environment for testing purposes.

Parameter Optional Description
engine No The blockchain engine to issue the job on

HTTP Request

POST https://api-demo.vizidox.com/api/jobs/immediate

Returns

If successful, the HTTP response is a 201 CREATED, along with a job object.

Errors

id code Description
missing_job 404 There is no job for the provided engine and partner
empty_credential_list 409 Can not issue job with an empty credential list
no_json 415 Request should contain a JSON payload
wrong_blockchain_engine 422 The provided blockchain engine is invalid
missing_field 422 Missing a field in the request body
insufficient_funds 503 Not enough funds to issue the credential(s)
try_again_later 503 Issuing is busy, try again later

Certificate

The Certificate Object

{
  "certificate": {
    "uid": "e2f52c36-7d39-48d7-8617-030891304cc2",
    "partner": {
      "id": "vizidox",
      "name": "Vizidox"
    },
    "credential": {
      "uid": "29d6f14e-a770-4f1c-8d6e-2e1aa4e9881a",
      "title": "Credential Title",
      "metadata": {"approved_by":  "John Smith"},
      "files": [
        {
          "file_hash": "056f32ee5cf49404607e368bd8d3f2af",
          "file_type": "image/jpeg"
        }
      ],
      "credentials": [],
      "upload_date": "2020-02-11T15:34:05.811954+00:00",
      "tags": [
        "tagA",
        "tagB",
        "tagC"
      ],
      "expiry_date": "2025-02-11T15:34:05.813229+00:00"
    },
    "issued_date": "2020-02-11T15:34:05.813217+00:00",
    "signature": "H+oPfLTKcG19O9yGgV1ftXPRXTvsMRXd22Uw8vyTuSlOTff+HUwvB8yFuKw/YzAFShDIvsjn4XBmsVGTb7iz2I8="
  },
  "revoked_date": null,
  "last_verification": {
    "status": "ok",
    "timestamp": "2021-05-07T19:21:04.813289+00:00"
  }
}

A Certificate is a verifiable descriptor for a credential issued over the Blockchain. The Certificate will contain all relevant data to connect the Credential to a Blockchain transaction. There is a one to one relationship between certificates, credentials and Blockchain engines: Each issued Credential has one Certificate per Blockchain engine.

Field Description
uid The unique identifier of the certificate
partner The partner who issued the certificate
credential The issued credential
issued_date The date the credential was issued on the Blockchain
signature Credential hashed and signed by the partner's key, which was issued
revoked_date Date of revocation, if applicable
last_verification The status and date of the latest verification of the certificate

Get All Certificates

curl -X GET "https://vizidox.com/api/certificates" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
certificates = vdx_helper.get_certificates(mapper, job_uid, cred_uid, uid, start_date, end_date, and_credential_tags, 
                                           or_credential_tags, and_job_tags, or_job_tags, verification_status, pagination)

Obtains all certificates issued by the partner. Includes the pagination arguments.

Parameter Type Optional Description
uid Query Yes Certificate UID to filter by
job_uid Query Yes Obtain certificates issued in job
credential_uid Query Yes Obtain the credential's certificate
issued_date_from Query Yes Obtain certificates that were issued after this date
issued_date_until Query Yes Obtain certificates that were issued up to this date
verification_status Query Yes Obtain certificates with a specific verification status

You can also use either the corresponding Credential or Job tags to search for certificates, even though the Core API does not support the addition of tags per certificates. These work in the same way as all other endpoints which contain tags as a filter option:

HTTP Request

GET https://vizidox.com/api/certificates

Pagination

sort_by parameter can be filled in with (Default is issued_date):

Returns

If successful, the HTTP response is a 200 OK, along with a paginated object containing the list of certificates.

Download Certificate JSON

curl -X GET "https://vizidox.com/api/certificates/<UID>/download" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
certificate_json = vdx_helper.download_certificate(certificate_uid)

Downloads a text file containing all relevant certificate data in a JSON format. Can also be called the proof file, and is usable for verification on the Core API.

Parameter Type Optional Description
cert_uid Path No Certificate UID to download

HTTP Request

GET https://vizidox.com/api/certificates/<UID>/download

Returns

If successful, the HTTP response is a 200 OK, along with a text file containing a JSON with the certificate data.

Errors

id code Description
missing_certificate 404 The certificate was not found

Verification

The Verification Object

{
  "verification": {
    "certificate": 
        {
          "name": "Checking certificate integrity",
          "description": {
            "hash_function": "SHA256",
            "actual_hash": "3fb4ef9b874803631b0fdd41f42bac952a2f5e9501d4e8ff3d0f13bd113435aa",
            "expected_hash": "3fb4ef9b874803631b0fdd41f42bac952a2f5e9501d4e8ff3d0f13bd113435aa"
          },
          "status": "passed"
        },
    "blockchain": 
        {
          "name": "Checking certificate is anchored to the blockchain",
          "description": {
            "actual_root": "1677894799b64e8f3c8ff1fa519ae3dab489fa86e2d6e2794e7c08a10290de95",
            "certificate_root": "1677894799b64e8f3c8ff1fa519ae3dab489fa86e2d6e2794e7c08a10290de95",
            "tx_id": "42d9914d9eee0d45ce870e1f56c0c5b71167754f03cc789bec8392fe20673730",
            "tx_url": "https://blockchair.com/bitcoin/testnet/transaction/42d9914d9eee0d45ce870e1f56c0c5b71167754f03cc789bec8392fe20673730",
            "confirmations": "3944"
          },
          "status": "passed"
        },
    "issuer": 
        {
          "name": "Checking issuer authenticity",
          "description": {
            "issuer_name": "Vizidox",
            "signature_scheme": "ECDSA",
            "partner_public_key": "mgiYnTTZmMG6SJAEBKd724YWFMLDrCF1Y1",
            "message": "c3c47e03d650bc3feffa24c5a2620ba1b4f894030df2ab2c6a809e7aa84c8c06",
            "signature": "H7E7JBfVt68MMLm9RlVXphPVsnwriC1DFF2iXOQ2VipDMWWd73agLskIc241UEplnhm/u7ChxkdoTUqqAOP0kWQ="
          },
          "status": "passed"
        },
    "file": 
        {
          "name": "Checking file integrity",
          "description": {
            "hash_function": "SHA3-256",
            "expected_file_hash": "5f476523425b99e128ea4de78763430e66c2bb75f99571b181104791a4f843f3",
            "actual_file_hash": "5f476523425b99e128ea4de78763430e66c2bb75f99571b181104791a4f843f3"
          },
          "status": "passed"
        },
    "expiry": 
        {
          "name": "Checking expiry date",
          "description": {
            "issued_date": "2021-09-24T14:30:08.056293+00:00",
            "expiry_date": null
          },
          "status": "passed"
        },
    "revocation": 
        {
          "name": "Checking revocation date",
          "description": {
            "is_revoked": false,
            "revocation_address": "mniEnS85X1iagmYYPNYDR9djtDufriEF2H",
            "revocation_address_url": "https://blockchair.com/bitcoin/testnet/address/mniEnS85X1iagmYYPNYDR9djtDufriEF2H",
            "revocation_date": null
          },
          "status": "passed"
        }
  },
  "result": {
    "status": "ok",
    "timestamp": "2021-10-21T14:45:55.207146+00:00"
  }
}

Verification is the process through which any issued credential can be validated. This only applies to credentials that have been fully issued on the Blockchain, so they cannot be simply scheduled for issuing.

The verification consists of six different steps, and can result in several results:

The obtained final result of verification will depend on the result of each individual verification step. If one step fails during the process, then no more steps will be tested since the credential is no longer considered valid by default. The six executed steps are:

Name Description
Certificate Integrity Checks if the Certificate has not been tampered with, including the credential metadata
Blockchain Anchoring Checks if the Credential has been issued and confirmed on the Blockchain
Issuer Authenticity Checks if the issuer's identity is valid
File Integrity Checks if the file has not been tampered with, retaining its original content
Expiry Date Checks if the credential is still valid as of this date
Revocation Date Checks if the credential has been revoked

Each of these steps have their own status at the end of the verification, and these are used to determine the final status. The possible verification step status are:

Verify By Certificate UID

curl -X GET "https://vizidox.com/api/verify/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
verification = vdx_helper.verify_by_uid(certificate_uid, mapper)

Verifies a Certificate via its unique identifier

Parameter Type Optional Description
cert_uid Path No Certificate UID to verify

HTTP Request

GET https://vizidox.com/api/verify/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

id code Description
missing_certificate 404 The certificate was not found

Verify By Credential UID

curl -X GET "https://vizidox.com/api/verify/credential/<UID>" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
verification = vdx_helper.verify_by_credential_uid(credential_uid, mapper, pagination)

Verify all certificates corresponding to the credential, via the credential's unique identifier. Includes the pagination arguments.

Parameter Type Optional Description
cred_uid Path No Credential UID to verify

HTTP Request

GET https://vizidox.com/api/verify/credential/<UID>

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

id code Description
missing_credential 404 The credential was not found

Verify By Certificate File

curl -X POST "https://vizidox.com/api/verify/upload/certificate" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.json;type=application/json"
verification = vdx_helper.verify_by_certificate(filename, file_stream, file_content_type, mapper)

Verifies a specific certificate, by uploading its certificate proof file

HTTP Request

POST https://vizidox.com/api/verify/upload/certificate

Returns

If successful, the HTTP response is a 200 OK, along with the verification result

Errors

id code Description
no_file_on_payload 400 No file was uploaded
missing_certificate 404 The certificate was not found

Verify By File

curl -X POST "https://vizidox.com/api/verify/upload/file" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>>" -H  "Content-Type: multipart/form-data" -F "file=@/path/to/file.pdf;type=application/pdf"
verification = vdx_helper.verify_by_file(filename, file_stream, file_content_type, mapper)

Verifies all certificates of the uploaded file Includes the pagination arguments.

HTTP Request

POST https://vizidox.com/api/verify/upload/file

Returns

If successful, the HTTP response is a 200 OK, along with a paginated list of all verification results

Errors

id code Description
no_file_on_payload 400 No file was uploaded
missing_certificate 404 The certificate was not found

Revocation

All issued credentials can be revoked if you need to. If for example, there was some error in the issued data and it should not be considered valid, revoking its corresponding certificate will guarantee that all future verifications fail.

Revoke Certificate By UID

curl -X POST "https://vizidox.com/api/certificates/<UID>/revoke" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"
revoked_date = vdx_helper.revoke_certificate(cert_uid)

Revokes a certificate, identified by its UID

Parameter Type Optional Description
cert_ui Path No Certificate UID to revoke

HTTP Request

POST https://vizidox.com/api/certificates/<UID>/revoke

Returns

If successful, the HTTP response is a 200 OK, along with the revocation date.

Errors

id code Description
missing_certificate 404 The certificate was not found
unconfirmed_certificate_transaction 409 The certificate blockchain issuing transaction has not yet been confirmed
certificate_already_revoked 409 The certificate has already been revoked

Revoke Certificate By Credential UID

curl -X POST "https://vizidox.com/api/credentials/<UID>/revoke/{engine}" -H  "accept: application/json" -H  "authorization: Bearer <TOKEN>"

Revokes the credential's certificate for the given Blockchain engine.

Parameter Type Optional Description
cred_uid Path No Credential UID to revoke
engine Path No Blockchain Engine of issuing

HTTP Request

POST https://vizidox.com/api/credentials/<UID>/revoke/{engine}

Returns

If successful, the HTTP response is a 200 OK, along with the revocation date.

Errors

id code Description
missing_credential 404 The credential was not found
missing_certificate_by_credential 404 The credential has not been issued on the given engine
unconfirmed_certificate_transaction 409 The certificate blockchain issuing transaction has not yet been confirmed
certificate_already_revoked 409 The certificate has already been revoked