API Reference Guide

The UR Code API provides a variety of functions for UR Code Generation & Verification, Identity Checks, and Image Comparison.

POST /create-ur-code-from-2d-image

Creates a UR Code from a 2D Image.

Parameters

images: Array of Base64 Images
url: String
metadataJSON: String
urCodeOutputUseTransparency: Boolean

Core Response Properties

urCodeCreationProcessingStatusEnumInt: FaceTecURCodeCreationProcessingStatus

0 = UR_CODE_CREATED_SUCCESSFULLY
1 = UNSUCCESSFUL_CHECK_2D_IMAGE_PROCESSING_STATUS
2 = UNSUCCESSFUL_DUPLICATE_IMAGE_DETECTED
3 = UNSUCCESSFUL_INVALID_UR_CODE_URL
4 = UNSUCCESSFUL_UR_CODE_TEMPLATE_MISSING_OR_INVALID
5 = UNSUCCESSFUL_UR_CODE_SCHEMA_MISSING_REQUIRED_FIELD

urCodeString: String — The full URL stored on the UR Code but optimized so that URL encoding is not needed. This helps decrease the overall size of the UR Code.
urCodeImage: Base64 Image — The UR Code as a PNG in Base64 format. The UR Code is returned as a lossless PNG to provide the highest quality image for optimal scanning. The resolution of the UR Code is provided at 1920x1920.
urid: String — A Unique Identifier for a UR Code.

Behavior

- Pass in a 2D image, URL, and metadata, and it creates/returns the UR Code Image and the full URL String encoded into it.
- The UR Code contains the Digital Signature of the UR Code data itself, signed by the UR Code Private Key.

POST /verify-ur-code

Verifies a UR Code and returns information from it. UR Codes are verified by using the Public Key, the UR Code Data, and the Digital Signature to ensure the UR Code has not been tampered with and was created by the owner of the Public Key.

Parameters

urCodeString: String -- The exact contents of the UR Code.

Core Response Properties

urCodeDataVerified: Boolean — True if the URID was verified, and the UR Code Data was verified against the signature.
metadataJSON: String — The metadata stored on the UR Code.

Behavior

- The metadata stored in the UR Code is returned.
- A UR Code is verified if the UR Code digital signature was validated by the Public Key and the digital signature matches the UR Code data.

POST /verify-ur-code-image

Verifies an image of a UR Code and returns information from it. UR Codes are verified by using the Public Key, the UR Code Data, and the Digital Signature to ensure the UR Code has not been tampered with and was created by the owner of the Public Key.

Parameters

urCodeImage: Base64 Image — A base64 JPEG or PNG image of a UR Code.

Core Response Properties

urCodeDetectedInImageStatusEnumInt: FaceTecURCodeDetectedInImageStatus

0 = UR_CODE_FOUND
1 = UNABLE_TO_DETECT_UR_CODE_IN_IMAGE
2 = UNABLE_TO_DECODE_IMAGE

metadataJSON: String — The metadata stored on the UR Code.
urCodeString: String — The full URL stored on the UR Code but optimized so that URL encoding is not needed. This helps decrease the overall size of the UR Code.
urCodeDataVerified: Boolean — True if the UR ID was verified, and the UR Code data was verified against the signature.
urid: String — A Unique Identifier for a UR Code.

Behavior

- The metadata stored in the UR Code is returned.
- A UR Code is verified if the UR Code digital signature was validated by the Public Key and the digital signature matches the UR Code data.

POST /match-2d-2d-ur-code

Matches a UR Code to a 2D Image.

Parameters

image: Base64 Image — A base64 JPEG or PNG used to match against the face data in the UR Code.
urCodeString: String — The exact contents of the UR Code.
minMatchLevel: FaceTecMatchLevel — Match Levels 1 - 6 can be specified.

Core Response Properties

success: Boolean — True if the UR Code data was verified to be the correct format, the digital signature was verified, and the Face Image matched with one of the Encoded Face Images with minMatchLevel or higher.
urCodeDataVerified: Boolean — True if the URID was verified and the UR Code Data was verified against the signature.
metadataJSON: String — The metadata stored on the UR Code.
matchLevels: Array of FaceTec Match Levels — Supported Match Levels are 0-6
urCode2DImageProcessingStatus: FaceTecURCode2DImageProcessingStatus — 0 = PROCESSED, 1 = UNABLE_TO_DECODE_IMAGE_DATA, 2 = UNABLE_TO_VALIDATE_IMAGE_MEETS_QUALITY_GUIDELINES
urid: String — A Unique Identifier for a UR Code.

Behavior

- success is true if the UR Code Data was verified, the digital signature was verified, and the FaceImage matched with one of the Encoded Face Images with minMatchLevel or higher.

POST /set-ur-code-public-key-map

Specifies the Public Keys that can be used to validate the UR Code’s Digital Signature. The UR Code Public Key Map is set by providing a JSON of URL to validate, and for each URL, a list of each of the valid Public Keys to use for Digital Signature Validation. When a UR Code is scanned, the URL from the UR Code is used to look up the Public Key(s) specified in the Public Key Map to try and validate the UR Code.

For more information, please see the UR Code Public Key Map.

Parameters

urCodePublicKeyMap: JSON Object — A JSON Object containing the map of URLs and their associated public keys.

Core Response Properties

success: Boolean — True if the public key map was set.

Behavior

- success is true if the public key map was set.