1. Introduction
    1. Prerequisites
  2. Integration
    1. API Endpoint
    2. Authentication
    3. Encryption
    4. Cross-Site Scripting (XSS)
  3. Scan Principles
    1. Scan Strategies
    2. Scan Codes
  4. Authentication
    1. Post User Login
  5. Scan Service
    1. Get Scan Services
  6. Barcode
    1. Get Barcodes
  7. Scan
    1. Post Checkin
    2. Post Checkout
    3. Post Upload
  8. Lookup
    1. Post Lookup

Ticket Scan API

The Ticket Scan API enables you to receive and scan barcodes for third party applications.

You can integrate this in your application by communicating with our api.

The Ticket Scan API is a REST API that uses JSON to communicate.

Related resources

Prerequisites

To make use of our API for Ticketing you need to be registered at CM.com, you need to be acquired in the ticketing app and you need to create an event in the ticketing app.

During the implementation you might have questions and we kindly refer to our Help Center documents to get more background information.

Integration

API Endpoint

  • Ticket Scan Api: https://api.ticketing.cm.com/scanapi/v2.0

Our API supports sending messages via HTTP. You can send a POST request containing a JSON body.

Authentication

The authentication consists of two parts: the application identifier and authentication with a JWT Token.

One JWT Token give you the possibility to retrieve information for scan user order.

The JWT Token can be requested with a combination of the username and the password.

The required header X-DEVICE-INFO and the JWT Secret will be provided by your account manager, or you can request one via [email protected].

Encryption

Communication with the CM servers should be done using the TLS cryptographic protocol, version 1.2 or higher. Older security protocols such as TLSv1.0, TLSv1.1 and SSLv3 are not supported.

Cross-Site Scripting (XSS)

On our API, Cross-Site Scripting (XSS) protection is enabled. XSS enables attackers to inject client-side scripts into web pages viewed by other users.

To protect your web application, and our API we disabled the option to make direct request from a web application.

Scan Principles

Scan Strategies

In our Ticket Scan API you are able to use different strategies:

Scan Locally

Scan locally (within your application) and sync afterwards. In this case you can use the following endpoints (in the given order):

  • Get Barcodes (in paginated pages with barcodes.)
  • Post Upload
  • Get Barcodes (with the X-COMPARE-TIMESTAMP header to retrieve the difference only.) 
    Note: syncing is important for the statistics within the dashboard to give you the correct analytics and insights.

Scan Direct

Scan direct on our servers. In this case you can use the following endpoints:

Scan Status Codes

Below you can find all available scan status codes with descriptions.

Code Message
40 DENY - Ticket barcode unknown: not accepted at this check-in point
45 DENY - Ticket is not allowed: this ticket type can not be scanned
50 DENY - Ticket already scanned: {last_checked_in_time} UTC
60 DENY - Ticket barcode is expired: on {expire_time} UTC
100 ADMIT - Ticket is valid
200 ADMIT - Ticket checked-out correctly
210 DENY - Can not check-out ticket: ticket already checked-out
220 DENY - Can not check-out ticket: no valid check-ins found
230 DENY - Can not check-out ticket: barcode not in service

Authentication

Authenticate to scan user information.

Post User Login

Post user login for a scan user to retrieve a JWT Token.

POST https://api.ticketing.cm.com/scanapi/v2.0/userlogin

POST Parameters

Type Name Description Required Example
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json

Request: User Login Object

{
  "credentials" : {
    "username": "some.username",
    "password": "some.password"
  }
}

Response

Http status Description Example
200 Successful operation User Login Object
401 Unauthorized Info Message

Response: User Login Object

{
    "login": {
        "message": "Successfully authenticated",
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJodHRwczpcL1wvY210aWNrZXRzLmNvbSIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwIiwiaWF0IjoxNTk0OTA2Njc2LCJleHAiOjE2MDAwOTA5NzYsInVzZXIiOnsidXVpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwIiwiYWN0aXZlIjp0cnVlfX0.XLsSEujtNxzQfr7CtT7VYzNYIbXEgSLykm0i5wgtOx2_CXR7EGZ44LRrfIlGFqlWLKvyjKg8_v_bXeHehtJlTQ"
    }
}

Retrieve Scan User uuid from JWT Token.

Once you have a successful response with a JWT Token you can find the scan user uuid in the jwt token payload. The "sub" or "user.uuid" property contains the correct Scan User uuid value which is needed for the other calls.

{
  "iss": "https://cmtickets.com",
  "sub": "00000000-0000-0000-0000-00000000000",
  "iat": 1594906676,
  "exp": 1600090976,
  "user": {
    "uuid": "00000000-0000-0000-0000-00000000000",
    "active": true
  }
}

Scan Service

A scan user can have multiple scan services which contains the barcodes.

Get Scan Services

Get the scan services data for a specific scan user.

GET https://api.ticketing.cm.com/scanapi/v2.0/users/{user_uuid}/services

POST Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Path Variable user_uuid The UUID of a scan user which can be retrieved from the JWT Token payload, you can use the property 'sub' or 'user.uuid'. True 00000000-0000-0000-0000-000000000000

Response

Http status Description Example
200 Successful operation Array of Scan Services Object
401 Unauthorized Info Message

Response: Scan Services Object

{
    "services": [
        {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "CM.com Scan Service",
            "description": "scan service for: CM.com",
            "setup": 2,
            "information_level": 1,
            "sync_interval": 120,
            "url": "https://api.ticketing.cm.com/scanapi/v2.0/",
            "count_total_available": 250,
            "permissions": [
                {
                    "uuid": "00000000-0000-0000-0000-00000000000",
                    "name": "checkin",
                    "description": "can manually checkin"
                },
                {
                    "uuid": "00000000-0000-0000-0000-00000000000",
                    "name": "checkout",
                    "description": "can manually checkout"
                },
                {
                    "uuid": "00000000-0000-0000-0000-00000000000",
                    "name": "lookup",
                    "description": "can lookup"
                }
            ],
            "ticket_types": [
                {
                    "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
                    "ticket_type": "Regular Ticket",
                    "total_available": 150
                },
                {
                    "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
                    "ticket_type": "VIP Ticket",
                    "total_available": 100
                }
            ]
        }
    ]
}

Barcode

Barcodes could be retrieved based on scan services.

Get Barcodes

Get the barcodes for a specific scan user.

GET https://api.ticketing.cm.com/scanapi/v2.0/services/{service_uuid}/barcodes

GET Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Header X-PAGINATION-LIMIT Amount of barcode per pagination page (preferable 500 or lower). True 500
Header X-PAGINATION-PAGE Current pagination page. True application/json
Header X-COMPARE-TIMESTAMP The timestamp which can be used to retrieve new updates after a certain moment (the compare time stamp.) False 1594912228
Path Variable service_uuid The UUID of a scan services which can be retrieved from the get scan services endpoint. True 00000000-0000-0000-0000-000000000000

Response

Http status Description Example
200 Successful operation Array of Barcodes Object
401 Unauthorized Info Message

Response: Barcode Object

{
    "pagination": {
        "total_items": 250,
        "total_pages": 1,
        "page_items": 250,
        "pages": {
            "current_page": 1,
            "first_page": 1,
            "last_page": 1,
            "previous_page": null,
            "next_page": null
        }
    },
    "barcodes": [
        {
            "barcode_id": "CMBARCODE123",
            "external_barcode_id": null,
            "batch_id": "CMORDER123",
            "ticket_type": "Regular Ticket",
            "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
            "subtitle": null,
            "first_name": "John",
            "sur_name": "Doe",
            "city": null,
            "email": "[email protected]",
            "mobile": "+31612345678",
            "serial_number": 1,
            "price": 10,
            "is_checkin_allowed": 1,
            "is_canceled": 0,
            "expire_from": null,
            "checkin_valid_from": null,
            "checkin_valid_till": null,
            "validation_max_checkins": 1,
            "remaining_scans": 1,
            "count_checked_in": 0,
            "last_checked_in_time": null,
            "last_checked_out_time": null,
            "section_id": null,
            "section": null,
            "row": null,
            "seat": null,
            "scan_status_code": null,
            "scan_status_message": null
        }
    ]
}

Scan

To actually start with scanning you can use the following scan endpoints (according to the Scan Strategies.)

A scan user can have multiple scan services which contains the barcodes.

Post Checkin

Post a checkin for a specific barcode.

POST https://api.ticketing.cm.com/scanapi/v2.0/barcodes/checkin

POST Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Body Checkin Object The checkin to make (JSON object.) True Checkin Object

Request: Checkin Object

{
    "user_uuid" : "00000000-0000-0000-0000-00000000000",
    "service_uuid" : "00000000-0000-0000-0000-00000000000",
    "barcode_id" : "CMBARCODE123"
}

Response

Http status Description Example
201 Successful operation Checkin Object
400 Bad request Info Message

Response: Checkin Object

{
    "barcodes": [
        {
            "barcode_id": "CMBARCODE123",
            "external_barcode_id": null,
            "batch_id": "CMORDER123",
            "ticket_type": "Regular Ticket",
            "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
            "subtitle": null,
            "first_name": "John",
            "sur_name": "Doe",
            "city": null,
            "email": "[email protected]",
            "mobile": "+31612345678",
            "serial_number": 1,
            "price": 10,
            "is_checkin_allowed": 1,
            "is_canceled": 0,
            "expire_from": null,
            "checkin_valid_from": null,
            "checkin_valid_till": null,
            "validation_max_checkins": 1,
            "remaining_scans": 1,
            "count_checked_in": 0,
            "last_checked_in_time": null,
            "last_checked_out_time": null,
            "section_id": null,
            "section": null,
            "row": null,
            "seat": null,
            "scan_status_code": 100,
            "scan_status_message": "ADMIT - Ticket is valid"
        }
    ]
}

Post Checkout

Post a checkout for a specific barcode.

POST https://api.ticketing.cm.com/scanapi/v2.0/barcodes/checkout

POST Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Body Checkout Object The checkout to make (JSON object.) True Checkout Object

Request: Checkout Object

{
    "user_uuid" : "00000000-0000-0000-0000-00000000000",
    "service_uuid" : "00000000-0000-0000-0000-00000000000",
    "barcode_id" : "CMBARCODE123"
}

Response

Http status Description Example
201 Successful operation Checkout Object
400 Bad request Info Message

Response: Checkout Object

{
    "barcodes": [
        {
            "barcode_id": "CMBARCODE123",
            "external_barcode_id": null,
            "batch_id": "CMORDER123",
            "ticket_type": "Regular Ticket",
            "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
            "subtitle": null,
            "first_name": "John",
            "sur_name": "Doe",
            "city": null,
            "email": "[email protected]",
            "mobile": "+31612345678",
            "serial_number": 1,
            "price": 10,
            "is_checkin_allowed": 1,
            "is_canceled": 0,
            "expire_from": null,
            "checkin_valid_from": null,
            "checkin_valid_till": null,
            "validation_max_checkins": 1,
            "remaining_scans": 1,
            "count_checked_in": 0,
            "last_checked_in_time": null,
            "last_checked_out_time": null,
            "section_id": null,
            "section": null,
            "row": null,
            "seat": null,
            "scan_status_code": 200,
            "scan_status_message": "ADMIT - Ticket checked-out correctly"
        }
    ]
}

Post Upload

Post scanned barcode results to our servers for syncing.

POST https://api.ticketing.cm.com/scanapi/v2.0/barcodes/upload

POST Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Body Upload Object The upload to make (JSON object.) True Upload Object

Request: Upload Object

{
  "user_uuid": "00000000-0000-0000-0000-00000000000",
  "service_uuid": "00000000-0000-0000-0000-00000000000",
  "barcodes": [
    {
      "barcode_id": "CMBARCODE123",
      "checked_in_time": 1594912228,
      "status_code": 100,
      "status_message": "ADMIT - Ticket is valid"
    },
    {
      "barcode_id": "CMBARCODE123",
      "checked_in_time": 1594912265,
      "status_code": 50,
      "status_message": "DENY - Ticket is not allowed: this ticket type can not be scanned"
    }
  ]
}

Response

Http status Description Example
201 Successful operation Upload Confirmation Object
400 Bad request Info Message

Response: Upload Confirmation Object

{
    "info": {
        "message": "Barcodes Inserted successfully."
    }
}

Lookup

You can use our API in order to search for parameters such as an order number or visitor name. The data property lookup_string needs to contain at least 3 characters. The API returns all barcodes matching your lookup value.

Post Lookup

Post a lookup for a specific parameter such as order number or visitor name.

POST https://api.ticketing.cm.com/scanapi/v2.0/barcodes/lookup

POST Parameters

Type Name Description Required Example
Header Authorization The JWT Token True bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3M...
Header X-DEVICE-INFO Device info is provided by CM. True DEVICE_ID:00000000-0000-0000-0000-00000000000,MANUFACTURER:X,MODEL:X,OS:X,OS_VERSION:X
Header Content-Type The content type which the application expects. True application/json
Body Lookup Object The Lookup to make (JSON object.) True Lookup Object

Request: Lookup Object

{
    "user_uuid" : "00000000-0000-0000-0000-00000000000",
    "service_uuid" : "00000000-0000-0000-0000-00000000000",
    "lookup_string" : "CMORDER123"
}

Response

Http status Description Example
200 OK Lookup Object
400 Bad request Info Message
404 Not found Resource Not Found: Barcode

Response: Lookup Object

{
    "barcodes": [
        {
            "barcode_id": "CMBARCODE123",
            "external_barcode_id": null,
            "batch_id": "CMORDER123",
            "ticket_type": "Regular Ticket",
            "ticket_type_hash_id": "00000000-0000-0000-0000-00000000000",
            "subtitle": null,
            "first_name": "John",
            "sur_name": "Doe",
            "city": null,
            "email": "[email protected]",
            "mobile": "+31612345678",
            "serial_number": 1,
            "price": 10,
            "is_checkin_allowed": 1,
            "is_canceled": 0,
            "expire_from": null,
            "checkin_valid_from": null,
            "checkin_valid_till": null,
            "validation_max_checkins": 1,
            "remaining_scans": 1,
            "count_checked_in": 0,
            "last_checked_in_time": null,
            "last_checked_out_time": null,
            "section_id": null,
            "section": null,
            "row": null,
            "seat": null,
            "scan_status_code": 100,
            "scan_status_message": null
        }
    ]
}

Our docs have migrated to our brand new Developers portal
Please use these for the most up to date experience.