Introduction

Welcome to Direct Connect: The Omniscan API!

This is the gateway to the Scanning Service for Go City. With our API, we provide the ability to validate the customers pass at your attraction in real-time.

A customer visits your attraction with a Go City pass. The pass has a pass number (confirmation code) and QR code to scan.

The Omniscan API allows you to validate that pass number (confirmation code) for entry to your attraction.

Once the pass is successfully validated, we update our own scan records to track its usage. So we will know if a pass has already been used for a particular attraction and cannot be used again.

Endpoints Summary

Our live production Omniscan can be accessed via this host:

• https://api.gocity.com

For testing purposes, please use:

• https://api.staging.gocity.tech

Our API provides the following resources:

Pass Region lookup

Check the local region of the pass

https://api.gocity.com/omniscan/terminal/passes/v1/{{confirmationCode}}/region

Pass Usage lookup

Look up available attractions for the pass

https://api.gocity.com/omniscan/terminal/passes/v1/{{confirmationCode}}

Pass Validation

Validate the pass for the attraction

https://api.gocity.com/omniscan/terminal/v1/{{confirmationCode}}

Authentication

Go City will provide you with a username and a password.

Each endpoint uses Basic Authentication.

Terms

Confirmation Code

• The customer's pass number.
• NB: Remove any hyphens from this code before passing to our API.

Terminal ID

• This is the same as your username.

Validation

• When the pass is scanned

Pass Region lookup

Look up the local region where the pass is expected to be applicable.

Request

URL: GET /omniscan/terminal/passes/v1/{{confirmationCode}}/region

Response

Sample Response:

{
    "region": "New York"
}

Response Object

Failure Response

If the Confirmation Code is not recognised when doing the region lookup. This will return a 400 HTTP Status.

Sample Failure Response:

{
    "errorType": "RESOURCE_NOT_FOUND",
    "error": "Unable to get pass region for confirmationCode: {{confirmationCode}}"
}

Pass Usage lookup

Look up available attractions for the Confirmation Code.

A list of attraction details will be returned with a visitPermission flag. This will be true if the attraction is still available - i.e: the customer has not redeemed their pass at this attraction yet.

Request

URL: GET /omniscan/terminal/passes/v1/{{confirmationCode}}

Response

Sample Response:

{
    "terminalId": "terminal01",
    "attractionList": [
        {
            "attractionId": 102100,
            "attractionName": "Attraction Name",
            "visitPermission": true
        }
    ]
}

Response Object

attractionList Data:

Failure Response

If the confirmation code has no available attractions:

Sample Failure Response:

{
    "terminalId": "terminal01",
    "attractionList": [
        {
            "visitPermission": false
        }
    ]
}

If the usage lookup fails unexpectedly"

Sample Failure Response:

{
    "errorType": "ERROR_CODE",
    "error": "Failed to lookup Pass Usage"
}

Pass Validation

Sample Request Body:

{
    "scanDate": "MM/dd/yyyy HH:mm:ss",
    "attractionId": 12345
}

Validate a pass for an attraction. Will return SUCCESS if the pass is allowed entry.

Request

URL: POST /omniscan/terminal/v1/{{confirmationCode}}

Request Body

Success Response

A customer's pass is valid for this attraction and they may enter.

Sample Response:

{
    "status": "SUCCESS",
    "message": "Admit One Adult",
    "scanDate": "MM/dd/yyyy HH:mm:ss",
    "confirmationCode": "{{confirmationCode}}",
    "terminalId": "{{terminalId}}",
    "passProvider": "SDI",
    "productType": "GO/EXP",
    "passType": "Adult",
    "attractions": [
        {
            "attractionId": 12345,
            "attractionName": "Some Attraction",
            "passProvider": "SDI"
        }
    ]
}

Failure Response

A pass validation may fail for a number of reasons including:

• Pass has already visited the attraction
• Pass is not allowed to visit the attraction
• Pass has expired
• Confirmation code is invalid

Please note that a validation fail will still result in a HTTP 200 OK response.

Sample Response (already visited):

{
   "status": "FAILURE",
   "message": "No Entry Already Visited",
   "scanDate": "06/25/2020 13:00:00",
   "confirmationCode": "{{confirmationCode}}",
   "attractions": []
}

Sample Response (invalid Confirmation code):

{
   "status": "FAILURE",
   "message": "Not a valid Confirmation Code format",
   "scanDate": "06/25/2020 13:00:00",
   "confirmationCode": "{{confirmationCode}}",
   "terminalId": "terminal01"
}

Warning Response

This will occur if the pass applies to more than one attraction, but no attractionId was provided.

In this case, the response will provide the list of available attractions, including the name and ID.

Then you will be able to set your chosen attractionId and send the scan request again.

Please note that this will result in a HTTP 200 OK response.

Sample Response:

{
    "status": "WARNING",
    "message": "Multiple Attractions for the Terminal: {{terminalId}}",
    "scanDate": "07/14/2020 13:00:00",
    "confirmationCode": "{{confirmationCode}}",
    "terminalId": "{{terminalId}}",
    "passProvider": "SDI",
    "productType": "GO/EXP",
    "passType": "Child",
    "attractions": [
        {
            "attractionId": 111111,
            "attractionName": "Night Tour",
            "passProvider": "SDI"
        },
        {
            "attractionId": 111112,
            "attractionName": "Daytime Tour",
            "passProvider": "SDI"
        }
    ]
}