Scanning API v1

The Scanning API allows you to validate the barcode (i.e. barcode string of the order) of the Enviso tickets sold on the direct/indirect sales channels as well as memberships sold on the direct sales channels.

All the information that passes the Scanning API is stored in Enviso.

Principles

The Scanning API is a REST API solution and attempts to conform to the RESTful design principles.

Note

Throughout the document, {version} stands for the first digit of the version in use.

Eg: If you are using version 1.0, {version} would mean v1

Important to know:

  • All connections must be made over HTTPS, not HTTP.

  • All the query parameters are to be passed in lower case.

  • All date and time data in the API request passed/response received are in the UTC-00:00 format.

    • yyyy-MM-ddTHH:mm:ssZ (Eg.: 1994-11-05T13:15:30Z)

Response status codes

The following HTTP status codes are used within the Scanning API.

Code

Description

200

OK

The request was successful, resulting in everything working as expected.

201

Created

The request was successful, resulting in the creation of a new resource.

202

Accepted

The request has been accepted for processing, but processing has not been completed.

204

No Content

The request was successfully processed, and is not returning any content.

400

Bad Request

The server was unable to understand the request. The request is most likely malformed or a mandatory parameter is missing.

Note

It is recommended to make modifications in the current request and repeat the request.

401

Unauthorized

The request has not been processed because it lacks valid authentication credentials for the target resource.

Note

If the request included valid authentication credentials, then the 401 response indicates that authorization has been refused for the target resource.

403

Forbidden

The server understood the request but refuses to authorize it.

Note

This probably means you did not pass the API Key (x-api-key) in your request headers.

404

Not Found

The requested resource does not exist.

Note

The resource may be available in the future. Subsequent requests by the client are permissible.

422

Unprocessable Entity

The server understands the content type of the request entity, but was unable to process the contained instructions.For example, this error condition may occur if validation rules to process the entity failed.

429

Too Many Requests

The server received too many request in a given amount of time.

500

Internal Server Error

The server encountered an unexpected error, which prevented it from fulfilling the request.

502

Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

503

Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Request headers

  • The request and response data is sent as JSON.

    content-type: application/json

  • The API Key is required to be passed in the HTTP Request Headers.

    x-api-key: your_api_key

  • The Tenant Key is required to be passed in the HTTP Request Headers.

    x-tenantsecretkey: your_tenant_key

  • The Authorization header is required for all endpoints.

    authorization: Bearer SPACE your_jwt_token

Error codes

Code

Message

7001

The barcode does not exist.

7002

The barcode is already scanned.

7003

The visit date/time is of the future.

7004

The visit date/time has already passed.

Permission

The user must have 'Full' permission for 'Scan barcode' from the Enviso Admin app in order to access the Scanning API endpoints.

Authentication

Contact Vintia support to obtain the Tenant key, API key and API secret key, which you need to start communicating to the API.

Once you have the needed information, you need to authenticate first before you'll be able to call the Scanning API.

For this, you'll need to use the Authentication API.

Going live

When going from the staging environment to the production environment:

  • Use the production environment API key and API secret key of the Authentication API.

Environment

Authentication API URL format

Staging

https://api.staging-enviso.io/authenticationapi

Production

https://api.enviso.io/authenticationapi

Use the production environment API Key and Tenant key of the Scanning API.

Environment

Scanning API URL format

Staging

https://api.staging-enviso.io/scanningapi

Production

https://api.enviso.io/scanningapi

Note

Contact Vintia support to get your production environment keys of the Authentication API and Scanning API.

Validate/Scan barcode (deprecated)

Validate barcode

POST /scanningapi/v1/validate/{barcode}

Validate the barcode and mark it as scanned, if valid.

Warning

This endpoint is deprecated and should no longer be used. Instead, use the endpoint Scan barcode.

URL parameter

Name

Type

Required

Description

barcode

string

true

The barcode value of the ticket/membership.

Eg: /v1/validate/EOWY2ALB0106FDTS

Responses

Success response code: 200 OK

Possible error codes

Code

Message

7001

The barcode does not exist.

7002

The barcode is already scanned.

7003

The visit date/time is of the future.

7004

The visit date/time has already passed.

Request
var client = new RestClient("https://api.staging-enviso.io/scanningapi/v1/validate/string");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
IRestResponse response = client.Execute(request);
Request
HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/scanningapi/v1/validate/string")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .asString();
Request
const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/scanningapi/v1/validate/string");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");

xhr.send(data);
Request
import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    }

conn.request("POST", "/v1/validate/string", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response
json
{
  "errors": [
    {
      "code": 0,
      "message": "string",
      "trace": "string"
    }
  ]
}

Validate/Scan pass (v2)

Scan barcode

POST /scanningapi/v2/scan/{passid}?accessreaderid={accessreaderid}

Validates the pass and marks it as scanned, if valid.

URL parameter

Name

Type

Required

Description

passid

string

true

The pass value of the ticket/membership.

Pass is the barcode of a single ticket or membership.

Eg: /v2/scan/EOWY2ALB0106FDTS

Query parameter

Name

Type

Required

Description

accessreaderid

GUID

false

Access reader ID linked to offer access zone.

Note

Reader ID will be required if the pass (offer) is linked with the access zone.

Eg: /v2/scan/EOWY2ALB0106FDTS?accessreaderid=f22b8fe7-1c3b-472f-879c-eaf7832e178b

Request body

Optional body 

{
	"ScanDate": "dateTime", 
	"SkipPeriodValidation": "bool",
	"SkipAccessTimeValidation": "bool"
}

Optional parameters

Parameter

Descripion

ScanDate

Sets the scanDate instead of utilising the current timestamp.

SkipPeriodValidation

Skips period validations (pass validity).

Default: False

SkipAccessTimeValidation

Skips access time validation (pass access times)

Default: False

Responses

Success response code: 200 OK

Possible error codes

Code

Message

1001

passId is required.

Possible reasons for access denied (accessdeniedreason)

  • The barcode is already scanned.

  • The visit date/time is in the future.

  • The visit date/time is already passed.

  • Currently there is no visit.

  • Pass not found.

  • Reader Id is required.

  • Invalid reader.

  • The zone access date/time is in the future.

  • The zone access date/time has already passed.

  • No access for today.

Request
var client = new RestClient("https://api.staging-enviso.io/scanningapi/v2/scan/string");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
IRestResponse response = client.Execute(request);
Request
HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/scanningapi/v2/scan/string")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .asString();
Request
const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/scanningapi/v2/scan/string");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");

xhr.send(data);
Request
import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string"
    }

conn.request("POST", "/v2/scan/string", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response
{
  "accessGranted": "bool",
  "accessDeniedReason": "string",
  "name": "string",
  "productName": "string",
  "holderName": "string",
  "holderPictureKey": "string"
}
json
{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Scan history

Scan history

GET /scanningapi/v2/passes/scanned?fromdate={fromdate}&todate={todate}&perpage={perpage}&pagetoken={pagetoken}

Gets a list of all scanned passes.

Query parameters

Name

Type

Required

Description

fromdate

DateTime

true

Start date of the search.

Eg: 2022-05-01T13:15:30Z

todate

DateTime

true

End date of the search.

Eg: 2022-05-04T23:59:59Z

perpage

Integer

false

Number of items to return per page.

Default: 25

Maximum: 250

pagetoken

String

false

Pagetoken to get the next set of the history.

When the token is null, there are no more results left.

Eg: eyJUZW5hbnRJZCI6eyJOIjoiNDQzIn0sIlNjYW5uZWREYXRlIjp7Ik4iOiIxNjY4NjgyMTQzIn0sIlJhbmdlS2V5Ijp7IlMiOiIwMDAwMDAxNjY4NjgyMTQzfEVPR1gyRFZHMjhDODZRRTUifSwiSGFzaEtleSI6eyJTIjoiNDQzfDEifX0=

Request body (Empty):

Response

Success response code: 200 OK

Possible error codes:

Code

Message

1001

fromDate required

1001

toDate required

1001

perPage required

1007

From date cannot be greater than the To date.

1008

Date range should not exceed a week

1009

Per page should not be greater than 250

Response body on success:

ScannedPass:

Response body on error:

Request
var client = new RestClient("https://api.staging-enviso.io/scanningapi/v2/passes/scanned");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
IRestResponse response = client.Execute(request);
Request
HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/scanningapi/v2/passes/scanned")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .asString();
Request
const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/scanningapi/v2/passes/scanned");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");

xhr.send(data);
Request
import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string"
    }

conn.request("GET", "/v2/passes/scanned", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response
{
}
Response
{
  "scannedPasses": "Array<ScannedPass>",
  "pageToken": "string"
}
Response
{
  "passId":"string",
  "scannedDate":"string",
  "productId": "number"
}
Response
{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}