API Reference

Basic usage

The Scantrust Photo-auth API is a publicly available REST API. There are 2 base domains:

https://api.staging.scantrust.io (test server)
https://api.scantrust.com (production server)

Photo-auth API

The authentication API requires a JPEG image as input.

It is rate-limited to 200 requests per minute.

POST /api/scan/photo/

Request

Headers

x-scantrust-app: String (required)

The app identifier. This app-id will be provided by scantrust.

Fields

image: File (required)

The image to run authentication on. The image MUST be a jpeg.

Response

Status Code

The response code is 200 in case of success, otherwise it returns one of the following values:

Return Code	Description
400	The posted data has a formatting issue. The client needs to check response details and adjust POST data accordingly before reposting
5xx	Server issue / bug: the load-balancer or authentication-server could be under maintenance or another issue is preventing it from running the authentication. If the issue persists, please contact Scantrust support

Data

The successful response is json-formatted and contains information about the authentication process as well as some information about the created scan object. The scan object is empty {} if no scan record was created.

authentication_status: String

Below is the result of the authentication process. It can take one of the following values:

authentication_status (String)	Description
auth_original	The secure graphic was authenticated as original.
auth_copy	The secure graphic was authenticated as a copy / a counterfeit.
auth_unknown	The authentication process lacks confidence to provide an answer.
auth_error	An error occurred during the authentication process and the secure graphic was not authenticated. This might happen when the image has severe quality issues or when the qr code is damaged.
bad_quality	The image quality was not sufficient to perform the authentication. More information can be found in the image_quality field to provide instructions for the user to improve the image quality of the next attempt.
sid	This code is just a Scantrust ID and not a scantrust secure code. Therefore, it has no secure graphic and can't be authenticated.
third_party	The content of the code was not recognised as a valid scantrust code. This usually happens when a user scans a third party code. It can also indicate a counterfeit attempt using a fake url. We recommend to prevent the user from redirecting to the content of this url as it can lead to untrusted content. No scan record is created.
not_read	No code was not read in the image. This can happen in the following situations: 1) no qr code was present in the image; 2) a qr code was only partially present in the image, or 3) our qr code detector / reader was not able to locate or read the qr code. No scan record is created.
not_found	The qr code content is valid scantrust content, however the code identifier was not found in the database. During the testing / UAT phase, this might happen if the code belongs to a different domain (test server vs production server). Otherwise it can be a counterfeit attempt. No scan record is created.
not_trained	No authentication model was found for the code. Secure QR codes are "trained" by Scantrust as part of the printing process, so this case is unlikely to happen on real products. If this issue occurs, please contact Scantrust support.
inactive	The code is not active. As part of the activation process, all scantrust qr codes are changed from “inactive” to “active” Inactive codes should never reach consumers / clients. If this issue occurs, please contact Scantrust support.
blacklisted	The code is blacklisted. Scantrust can blacklist codes for several reasons, such as overprint, damage (returns), excessive scanning, etc, A common way for a qrcode to become blacklisted is if there have been identified counterfeit attempts.

image_quality: Array of Strings

Below is a list of quality issues found in the image. This information can be used to guide the user for the following attempts (if needed). Here is the list of possible quality issues:

image_quality (Array of Strings)	Description
too_big	The code is too big. The user should scan from further away or should decrease the zoom level.
too_small	The code is too small. The user should either move closer or increase the zoom level.
blurry	The image is blurry. The user should improve the focus when capturing the image.
glare (deprecated)	There is too much glare in the image. This is usually caused by light reflections either from external lights or by the device’s flashlight. The user should find a better angle to avoid these reflexions.
generic	Our neural network algorithm found and issue but we don't know the exact cause of the quality issue. This could be any of the issue listed above.

image_roi: Array of four integers

ROI (region of interest) for the secure graphic in the image. This list consists of the top left corner x and y positions and the width and height of this region [top_left_x, top_left_y, width, height]. This can be used to extract the secure graphic from the image in order to display it. This field is not null only if authentication_status is auth_original, auth_copy or bad_quality.

carrier_content: String

Content of the code read in the image. This field is null if the code was not read.

scan: Object

Information about the created scan. Useful fields are:

scan (Object)	Description
product	Object with name, landing page url and image url (empty string or null if none) of the product.
brand	Object with name, description, landing page url and image url (empty string or null if none) of the brand.
consumer_url	Url of this specific item. Usually used to redirect the user.

Example

POST example (multipart/form-data)

[POST] https://api.staging.scantrust.io/api/scan/photo/
--6856697c0fe2dc3eb3aed07ae7b5925d
Content-Disposition: form-data; name="image"; filename="file.jpeg"

<BINARY DATA>
--6856697c0fe2dc3eb3aed07ae7b5925d--

Response example

{
  "authentication_status": "auth_original",
  "image_quality": ["blurry","glare"],
  "image_roi": [1764,1302,534,533],
  "carrier_content": "https://QA1.CH/Q/h2Jn_9tBQaAT",
  "scan": {
    "uuid": "bbac5b99-f16d-4246-81c4-dcc7c56a540a",
    "app": "other",
    "reason": "auth",
    "result": "ok",
    "auth_failure_mode": "",
    "activation_status": 1,
    "blacklist_reason": 0,
    "is_blacklisted": false,
    "product": {
      "id": 6104,
      "name": "test test test",
      "url": "http://scantrust.com",
      "image": ""
    },
    "brand": {
      "name": "Clothing",
      "description": "qa",
      "image": null,
      "url": "http://scantrust.com"
    },
    "scm_data": {},
    "consumer_url": "http://scantrust.com",
    "unreadable_retries": 0,
    "training_status": 2,
    "ga_key_app": "",
    "is_consumed": false,
    "bypass_scan_result": true,
    "serial_number": "ZE5TVP6X"
  },
}

Basic usage​

Photo-auth API​

POST /api/scan/photo/​

Request​

Response​

Basic usage

Photo-auth API

POST /api/scan/photo/

Request

Response