Introduction

The API is based on industry standard REST principles and uses secure tokens based on RFC 7519 for representing claims securely between two parties.

This API and documentation for developers to start working on applications. Do check back regularly on this document for updates.

Please note the tokens illustrated here are for demo purposes and subject to expiry. Please use the tokens provided by Qryptal for your development. Sign up for a trial account at Qryptal or contact support@qryptal.com to request for test tokens, if you have not already received it.

Searching for the old documentation?

Check out our old documentation.

End point

The API URL that will be used for your organization is of the format

Base URL Format

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes

Getting Started

To call an API, you'll need a token which is available when you sign up for Qryptal, one token for testing and another for production use.

To call the API, you'll need the token that was generated and displayed in the Tokens tab on the admin page, there are two tokens displayed one for testing and another for production use.

To try out the API, please go to API Call section.

Request Header [POST]

Authorization Header

Authorization: Token <token>

[Example] Authorization Header

Authorization: Token [PDC]eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrc3AiOjAsInR0IjoiRTEiLCJvcmdfaWQiOjExLCJrMSI6IkRXaWI1WDhJVjNJNGV6SDA1VzF2TGsiLCJha2lkIjoxLCJleHAiOjIyODMxNzAzNDQsInZxdHlwZSI6IlBEQyJ9.-6EPuBRQTBdbsJlAJnixSgupSdbPUn661t2OHWhet6Q

Types of Qryptal Codes

There are 2 types of Qryptal Codes that can be generated.

Each requires a different token to generate them. The two types are known as PDC - Primary Data Code and EDC - Extended Data Code

To find out more about the QR types and what they can do for you follow this link

The documentation below will indicate if certain features are available only for EDC such as revocation and attaching files (pdf, images etc). Otherwise all other information is to both code types and token used can be replaced with either ones.

PDC - Primary Data Code

Suitable for storing Textual Data
The token provided to generate this is prefixed with [PDC] to distinguish it.
All data is stored within the QR Code that is generated. The data cannot be updated or to revoke the code.
With Qryptal's Multi Pipeline Compression (QMPC). Data up to about 1.5KB can be stored for a typical printable QR code size of about 3 cm by 3 cm

EDC - Extended Data Code

Suitable for storing attachments (images/pdf) or more data and/or Codes that need to be updated/revoked
The token provided to generate this is prefixed with [EDC] to distinguish it.
Only minimal data is stored in the QR. All additional data is stored encrypted in an Additional Data Repository (ADR) on your local system
Network connectivity to the QSCS system - QVAL server is required for verification
The amount of data that can be stored is practically limited to 25 MB/code.
The QR Code size is small and consistent. Typically 1.6 cm x 1.6 cm

Creating a Qryptal Secure QR Code

Qryptal provides for organizations to generate secure Qryptal secure codes via APIs

The data and its corresponding format must be supplied for each data. The format object is used to indicate how the data is to be displayed on the mobile device when the QR is scanned. In the example, "t2" format indicates a basic key - value pair display.

For other data and display formats including photo support, see Data Types section.

Scheme

There are 2 supported schemes for this API version.

“CO2” as shown above is the most commonly used. This generates a secure code that can be verified using your phone's camera on the verification website or using Qryptal's Validation app. For an example, visit verify.demo-university.com
“CO2U” this will return a URL based QR that can be scanned with most modern phone's camera without the need for an app. It is more convenient, though slightly less secure due to it being a URL. The digital signature of the content is verified just as before to verify that it is not tampered before the result is presented.

Please store in your own database record the "uid" and "code_token" associated with this QR code generation as it can be used for tracking and future updates including possibly revocation of the code if it's permitted.

To list codes created, The API is :

[GET] Endpoint Structure

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes?token=<token>

Demo

The figure below shows a detailed illustration of the API Payload structure

Sample POST Request

Payload

{
  "data": {
    "Name": "Jack Smith",
    "Maths": "99"
  },
  "format": {
    "fields": [
      {
        "Name": {
          "type": "t2"
        }
      },
      {
        "Maths": {
          "type": "t2"
        }
      }
    ],
    "version": "1"
  },
  "scheme": "C02"
}

Python

import requests
headers = {
  "Authorization": "Token [PDC]eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrc3AiOjAsInR0IjoiRTEiLCJvcmdfaWQiOjExLCJrMSI6IkRXaWI1WDhJVjNJNGV6SDA1VzF2TGsiLCJha2lkIjoxLCJleHAiOjIyODMxNzAzNDQsInZxdHlwZSI6IlBEQyJ9.-6EPuBRQTBdbsJlAJnixSgupSdbPUn661t2OHWhet6Q"
}
ep = "https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes"
files = {}
payload = {...}
data = {
  "payload": json.dumps(payload)
}
response = requests.post(ep, files=files, data=data, headers=headers)

Response

{
  "id": 60167,
  "ct": "2020-04-24T06:36:18.935949Z",
  "status": "C",
  "msg": "success",
  "vqtype": "PDC",
  "uid": "1097580178100010000601672116",
  "code_token": "C02:rFKsq1dyUmJZZFNze1JrUmJolWaVYmppY5RibmdpnW6ampRinHFplGiUkpWRZWFqZ5eZa5SSYmZlkm5ua2xnZ5qcaWGSlJNkk2JmaJRknGtUXVOlo5eYoJlaamJoZFOblamQmZRSamdhrg==",
  "qrurl": "https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1097580178100010000601672116/qr1097580178100010000601672116.png?code_token=C02:rFKsq1dyUmJZZFNze1JrUmJolWaVYmppY5RibmdpnW6ampRinHFplGiUkpWRZWFqZ5eZa5SSYmZlkm5ua2xnZ5qcaWGSlJNkk2JmaJRknGtUXVOlo5eYoJlaamJoZFOblamQmZRSamdhrg==",
  "apitype": "G",
  "scheme": "C02",
  "qr_text": "C02::1097580178100010000601672116:1.4MBT$NE$QV7.SP351NAJAJIM9 IEX6%ZBF0.J9KEMYXYRN-11-11-:HDP4Z5N5JX$XV+H./.AMBU**.XH6OE3 %*.HG59W6.1XU6Y-A9OQ%U/XUWEILY*4B3VAOCJ%Q$T2M5WLM6G.N5FHXUJ*3KZ:QGMCU79CF5DH /A9A Q /HE.JAE3A*NJBB5//P+Y%KPAJYL4*N2QDN1CGXLC3U4869B8A/RM.IBT4BNMJV.WP.*7XJ0$9VVN8C4II/3NW6OTHG911YG6TAFFY7I6E06K4KCB"
}

Created QR Code

Code Creation Status

The JSON payload returns the status as follows:

P: Processing: The request is being processed
C: Created : The Code has been created successfully
E: Error: There was an error in creating the code

Response Structure

qr_text string

Value returned is the content of the QR. This will enable consumers of the API to create their own QR image.

qr_url string

Alternatively, the “qr_url” is provided to fetch the QR image of various sizes and with white/transparent background.

Checking Status of Code Creation Request

[GET] Endpoint

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/</id>/?token=<token>

Saving the QR Image

The JSON response parameter "qrurl" will contain the URL to fetch the image. Preview Sample

[GET] qrurl Structure

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1004698934100010000000131849/qr1004698934100010000000131849.png?token=<token>&code_token=<code_token>

Transparent Background

By default the image is a white background. To get an image with a transparent background, add the bg=0 to the URL parameter. Preview Sample

[GET] bg Structure

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1004698934100010000000131849/qr1004698934100010000000131849.png?token=<token>&code_token=<code_token>&bg=0

Image Size

Twelve (12) Image sizes are available for download to test which size works best for your needs. To specify the size, add the s=4 for example to the URL parameter. Preview Sample

[GET] s Structure

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1004698934100010000000131849/qr1004698934100010000000131849.png?token=<token>&code_token=<code_token>&bg=0&s=4

QR Code Verification

Test / Verify QR Code

To test the QR Code image created, visit verify.demo-university.com using your mobile phone or download the QR Validator app available on the same page.

Document validator app available via: https://qryptal.app/

Test / Verify QR Code URL

Validation URL Format

https://verify.demo-university.com

Example of how it appears on the phone browser.

QR Codes with Attachments

EDC Codes

The following sections work with EDC Tokens Only. Please contact support@qryptal.com to request for test tokens if you have not received them.

Secure EDC QR Codes provide the ability to store a lot of data including attachments. They also provide for the ability to revoke a code.

Currently, there are two versions of the JSON payload that can be sent when generating

Version 1 : with code attachments i.e PDF, images etc
Version 2 : For larger Text only with separation of display format and data

Creating a QR Code with Attachments

Code Attachments are files such as images and documents added to the secure codes

To add these attachments, send the POST API request as a 'multipart/form-data' content type with the payload field along with the files attached.

Attachments are to be indicated in the JSON payload as fields in the format section of the payload.

Example

Profile.jpg is specified in the highlighted section in the payload below. This will display as "Profile.jpg" and expects the POST data to have the image data in the field "img1" . Similarly for "Amazon-CaseStudy.pdf" the file data is sent in the field "file1" etc

EDC Payload Version 2

EDC codes without code attachments is similar to the PDC data format, however, the key differences to note are:

Display Format and data separation. In the below example, the QR will display the label Full Name with the data obtained from the data.Name field
This provides more flexibility in how the data fields are defined and how it is being displayed when using the app.

[EDC Payload] Version 1

Payload v1

{
  "data": {
    "Name": "Jeff Bezos",
    "Position": "Founder Amazon"
  },
  "format": {
    "version": "1",
    "fields": [
      {
        "Name": {
          "type": "t2"
        }
      },
      {
        "Position": {
          "type": "t2"
        }
      },
      {
        "Profile.jpg": {
          "type": "f1",
          "file_type": "jpg",
          "file_field": "img1"
        }
      },
      {
        "Amazon-CaseStudy.pdf": {
          "type": "f1",
          "file_type": "pdf",
          "file_field": "file1"
        }
      },
      {
        "Amazon-10K.pdf": {
          "type": "f1",
          "file_type": "pdf",
          "file_field": "file2"
        }
      }
    ]
  }
}

[EDC Payload] Version 2

Payload v2

{
  "data": {
    "Maths": "99",
    "Name": "Jack Smith"
  },
  "format": {
    "fields": [
      {
        "Full Name": {
          "type": "t2",
          "kval": [
            "Name"
          ]
        }
      },
      {
        "Maths Marks": {
          "type": "t2",
          "kval": [
            "Maths"
          ]
        }
      }
    ],
    "version": "2"
  },
  "scheme": "C02"
}

Data Types

The data format types used above are overlaid in red and explained below

2 column key: value display
e.g: Name: Jack Smith

t2 with bold

{"type":"t2", "m":"b"}
e.g: Transactions (here only key field is given and the value field left blank),
"m": "b" indicates bold

1l3-2l1

("l" is the small letter L)
3 columns with a line of text below in a small font. All text left aligned

4T1P - Photocard

Row with 2 columns
1st column up to 4 lines of text on the left (left aligned)
2nd column with a photo on the right column

f1 - File Attachments

e.g.,"type": "f1" - denotes its a file field and requires "file_type" and "file_field" to be passed as well

Here's an example to illustrate data types available

Payload

{
  "data": {
    "Name": "Jack Smith",
    "Account": "9939399",
    "Transactions": "",
    "Transaction_Log": [
      [
        [
          "18-Mar",
          "CR",
          "500.00"
        ],
        [
          "Cash Deposit"
        ]
      ],
      [
        [
          "25-Mar",
          "CR",
          "12800.00"
        ],
        [
          "Salary J.P. Morgan Chase"
        ]
      ]
    ],
    "PhotoCard": [
      [
        "Jack Smith",
        "22-Mar-1980",
        "Melbourne",
        ""
      ],
      [
        "/9j/4AAQSkZJRgABAQAASABIAAD/4QCMRXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABIAAAAAQAAAEgAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAABygAwAEAAAAAQAAACMAAAAA/+0AOFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAAOEJJTQQlAAAAAAAQ1B2M2Y8AsgTpgAmY7PhCfv/AABEIACMAHAMBIgACEQEDEQH/xAAfAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgv/xAC1EAACAQMDAgQDBQUEBAAAAX0BAgMABBEFEiExQQYTUWEHInEUMoGRoQgjQrHBFVLR8CQzYnKCCQoWFxgZGiUmJygpKjQ1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4eLj5OXm5+jp6vHy8/T19vf4+fr/xAAfAQADAQEBAQEBAQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQgUQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2dri4+Tl5ufo6ery8/T19vf4+fr/2wBDAAcHBwcHBwwHBwwRDAwMERgRERERGB4YGBgYGB4kHh4eHh4eJCQkJCQkJCQrKysrKysyMjIyMjg4ODg4ODg4ODj/2wBDAQkJCQ4NDhkNDRk7KCEoOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozv/3QAEAAL/2gAMAwEAAhEDEQA/APafFfia38L6a146ebKQxjjzgHaMkscHCjucV5X/AG9eG5ebXtR3XgUP5EQlaCJTzhFi2h2xjO5ifTGcV2HjWyN74l8O20vzQTzTRyKehATfg+x24r0OJLSMC2iCLsGAi44H0oA8Y8OeMIkv/M/tC9voZFxteEpAhPTLuNynjaMtgk98ivaLW5hvLeO6gOUkUMpIxwfaq17DplzA+mXojaO4Uq0TY+YH2rM8JMz6DBIzbg5cqf8AZ3HH5jmgD//Q9zuYFbWIZp13qnMf+y2CC2evQkfjT49MsbK+N2rlHkAUD6HP/wCutO4h81QwALoQy/Uf41my20lxH5trId2NrhsZOOgJwSCKAGLp9tc3P2yRj5sTENg8euCOhGOnpT9IgZbMbSUQsSi+i9se3pTI7acRxxTMS7EsVGAF4x2/Hr3rcAAGBwBQB//R+karvGgYygYY8EjjP1qxUUnSgBIUVV3Dq3Unk1NUcf3BUlAH/9k="
      ]
    ]
  },
  "format": {
    "header": "Use Document Validator App",
    "fields": [
      {
        "Name": {
          "type": "t2"
        }
      },
      {
        "Account": {
          "type": "t2"
        }
      },
      {
        "Transactions": {
          "type": "t2",
          "m": "b"
        }
      },
      {
        "Transaction_Log": {
          "type": "1l3-2l1"
        }
      },
      {
        "PhotoCard": {
          "type": "4T1P"
        }
      }
    ],
    "version": "1"
  },
  "scheme": "C02"
}

Note

Photo image has to be sent in base64 as part of the payload with type stripped off e.g "data:image/png;base64," removed

API Call Examples Using default config
to use your org config please login here Login

Configuration

Endpoint

{{endpoint}}/v2/Vqodes

Below API call will use a test token, nothing will be charged

Generate QR PDC

Endpoint

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes

Authorization

Token <hidden>

Body

payload dict

A dictionary containing "data", "format" and "scheme" for QR generation.

Payload Editable

Response

{
  "id": 852158,
  "ct": "2022-12-20T09:27:13.947154Z",
  "status": "C",
  "msg": "success",
  "vqtype": "TPDC",
  "uid": "1181398433100010008521582322",
  "code_token": "C02:rFOrpVVzWmVVX1Nze1JrUpSVamaXapdrmJWWaJSUbmWVnppmY2mUYWVoYWGUYGhlaWJtmZOUamhjaG5qmHFumGZoaZRllWVhYmNxm2eXm3BUX1Sho5iXmpdbcmVkX1OblamQmZRScmZjrg==",
  "qrurl": "https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1181398433100010008521582322/qr1181398433100010008521582322.png?code_token=C02:rFOrpVVzWmVVX1Nze1JrUpSVamaXapdrmJWWaJSUbmWVnppmY2mUYWVoYWGUYGhlaWJtmZOUamhjaG5qmHFumGZoaZRllWVhYmNxm2eXm3BUX1Sho5iXmpdbcmVkX1OblamQmZRScmZjrg==",
  "apitype": "G",
  "scheme": "C02",
  "qr_text": "C02:Use Document Validator App:1181398433100010008521582322:1R6E8KI.SG21I0MG8QZ RRSCWZPBWUBFQ8Q.+XL%AZ+SFD 3B-11-11-:8T%XZI89F.PZO7B$MM.4UNLZH+GYB%0+JBFJH$01.YLZMJV-3.FCZ9Y5WWO2J*YT8UNZJB/788763GTNB665K4B4GBE+EPMB:.HB7J692OO$J. O13 TYSHMFT8K4+8O*$UW2%TV NKH/  M1WCZX*BKC.2ESB1$0M+W1X606LHH%DH5Z*NYHS24DK7F1$ANWG HKDD2$C7G46L0 9SY+7$9/TA6MQUS$FP6TBVFKX+GS U7KTK4E85Z4XNFO%27C2 C249.Z3K7ZN97.01E9ZI/VIVSR5K1*/WNW73IYM%0I28E+CBRHR$D/Z4DSRU/P2YL56GZ8/HLPZKZC*D9RXUMYC %/.BAKJ..Q*6UTI7UQ  7XR1J3II64D47A8%%NNCLJXQTW*J"
}

Generate QR EDC (with attachments)

Endpoint

https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes

Authorization

Token <hidden>

Body

payload dict

A dictionary containing "data", "format" and "scheme" for QR generation.

img1 Use prefilled or choose another file

Choose a Photo PNG file for ID Card for the format_edc

file1 Use prefilled or choose another file

Choose a PDF file for the Certificate in the format_edc

Payload Editable

Response

{
  "id": 852187,
  "ct": "2022-12-20T09:51:13.854681Z",
  "status": "C",
  "msg": "success",
  "vqtype": "TEDC",
  "uid": "1181399873100010008521878384",
  "code_token": "C02:rFOrpVVzW2pZX1Nze1JrUmZpbJdpZ2poa2SbZ2lqmZdpm59wnGpqkmlilGNhY3FraJZob3BqnGRpk56UY3KbbJhpYZaRlmVllWmZa2NpnJ1aX1qjo5iXmpdbc2pjVZyVqY-alFJqarI=",
  "qrurl": "https://api2test.qryptal.com/v2/Vqodes/v2/Vqodes/1181399873100010008521878384/qr1181399873100010008521878384.png?code_token=C02:rFOrpVVzW2pZX1Nze1JrUmZpbJdpZ2poa2SbZ2lqmZdpm59wnGpqkmlilGNhY3FraJZob3BqnGRpk56UY3KbbJhpYZaRlmVllWmZa2NpnJ1aX1qjo5iXmpdbc2pjVZyVqY-alFJqarI=",
  "apitype": "G",
  "scheme": "C02",
  "qr_text": "C02::1181399873100010008521878384:2DY1AOC9F%+4QXK0 VD95A$QM6XC.*4UGGPFIUUTNXAH4FX8-2-2-:3E8FSOFWEQPT%7V5GZ9CBA2DH%$2KW+CE.YMIO1E$0DQAYH-0G.4+V0+GFKX.FS2GV.OD3HLOGS OBOMA9VHCOPG5DMST%1B:"
}

Other API Endpoint

To try out Revoke, Update, and Validation API use the Postman App

A sample zip file containing the JSON payload as well the attachments can be downloaded here: QryptalDemoCodeAttachments.zip

Qryptal Validation Codes Web Service API Reference 2.0 Qryptal API Ref 2.0

Introduction

Base URL Format

Getting Started

Authorization Header

[Example] Authorization Header

Types of Qryptal Codes

Creating a Qryptal Secure QR Code

[GET] Endpoint Structure

Payload

Python

Response

Created QR Code

[GET] Endpoint

[GET] qrurl Structure

[GET] bg Structure

[GET] s Structure

QR Code Verification

Validation URL Format

QR Codes with Attachments

Payload v1

Payload v2

Data Types

Payload

API Call Examples Using default config to use your org config please login here Login

Configuration

Endpoint

Endpoint

Authorization

Payload Editable Try it out

Response

Endpoint

Authorization

Payload Editable Try it out

Response

Other API Endpoint

API Call Examples Using default config
to use your org config please login here Login

Payload Editable

Payload Editable