Check Bundle

Endpoint

• Method: GET

• Path: /api/v4/check_bundle

• Description: Checks the status and validity of a license bundle.

Authentication

See License API Authorization.

Required headers

• Date (string) — RFC7231 GMT date string

• Authorization (string) — signature or bearer token

Recommended headers

• Accept: application/json

Request

Query parameters

Required:

• hardware_id (string)

• product (string) — Bundle product short code

One of:

• license_key (string)

• username (string)

Optional:

• license_id (number)

• include_expired_features (boolean)

• env (string)

• os_ver (string)

• hostname (string)

• os_hostname (string)

• ip (string)

• ip_local (string)

• app_ver (string)

• sdk_ver (string)

• mac_address (string)

Examples

curl

curl --location --request GET '/api/v4/check_bundle?hardware_id=string&product=string&license_key=string' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string'

nodejs

javascript (fetch)

python

ruby

---

Schema

Request Query Parameters

Request schema (TypeScript + JSON Schema)

TypeScript

type BundleCheckQueryParameters = ({

  // for key-based licenses:
  license_key: string

} | {

  // for user-based licenses:
  username: string

}) & {

  // required properties:
  hardware_id: string
  product: string

  // optional properties:
  license_id?: number | undefined
  is_vm?: boolean | undefined
  vm_info?: string | undefined
  os_ver?: string | undefined
  hostname?: string | undefined
  os_hostname?: string | undefined
  ip?: string | undefined
  ip_local?: string | undefined
  app_ver?: string | undefined
  sdk_ver?: string | undefined
  mac_address?: string | undefined
  include_expired_features?: boolean | undefined
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "items": {
    "allOf": [
      {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "license_key": { "type": "string" }
            },
            "required": ["license_key"],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "username": { "type": "string" }
            },
            "required": ["username"],
            "additionalProperties": false
          }
        ]
      },
      {
        "type": "object",
        "properties": {
          "hardware_id": { "type": "string" },
          "product": { "type": "string" },
          "license_id": { "type": "number" },
          "is_vm": { "type": "boolean" },
          "vm_info": { "type": "string" },
          "os_ver": { "type": "string" },
          "hostname": { "type": "string" },
          "os_hostname": { "type": "string" },
          "ip": { "type": "string" },
          "ip_local": { "type": "string" },
          "app_ver": { "type": "string" },
          "sdk_ver": { "type": "string" },
          "mac_address": { "type": "string" },
          "include_expired_features": { "type": "boolean" }
        },
        "required": ["hardware_id", "product"],
        "additionalProperties": false
      }
    ]
  }
}

---

Response Body

Response schema (TypeScript + JSON Schema)

TypeScript

type BundleCheckResponseBody = BundleCheckResponse[];

type BundleCheckResponse = {
  id: number,
  allow_grace_period: boolean,
  allow_overages: boolean,
  allow_unlimited_activations: boolean,
  borrowed_until: string | null,
  can_borrow: boolean,
  channel: string,
  device_id: number,
  enable_maintenance_period: boolean
  environment: string,
  eula_link: string,
  floating_timeout: number,
  grace_period: number,
  hash_md5: string,
  installation_file: string,
  is_air_gapped: boolean,
  is_borrowed: boolean,
  is_expired: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  is_hardware_key_auth: boolean,
  license_active: boolean,
  license_enabled: boolean,
  license_signature: string,
  license_signature_v2: string,
  offline_signature: string,
  license_type: string,
  maintenance_period: string | null,
  max_activations: number,
  max_borrow_time: number,
  max_license_users: number,
  max_overages: number,
  max_transfers: number,
  order_store_id: string,
  prevent_vm: boolean,
  release_date: string,
  release_notes_link: string,
  requires_version: string,
  size: string,
  start_date: string | null,
  times_activated: number,
  transfer_count: number,
  validity_period: string | null, // string is in DateISO8601UTC format
  version: string,
  company: { id: number },
  
  product_features: ({
    id: number,
    code: string,
    name: string,
    expiry_date: string,
    metadata: JSON,
    feature_type: 'activation' | 'consumption',
    is_floating: boolean,
    is_floating_cloud: boolean,

    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_users: number,
    floating_timeout: number,

    // the following properties are only present if feature_type=consumption
    max_consumption: number,
    allow_unlimited_consumptions: boolean,
    total_consumptions: number,
    allow_overages: number,
    max_overages: number,
    reset_consumption: boolean,
    consumption_period: 'daily' | 'weekly' | 'monthly' | 'annualy' | null,
  })[],
  
  custom_fields: ({
    name: string,
    data_type: 'numer' | 'text' | 'date/time',
    value: string,
  })[],
  
  customer: {
    email: string,
    company_name: string,
    reference: string,
    phone: string,
    first_name: string,
    last_name: string,
    city: string,
    postcode: string,
    state: string,
    country: string,
    address: string,
    customer_account: string | null,
    metadata: JSON,
  },
  
  product_details: {
    product_id: number,
    product_name: string,
    short_code: string,
    authorization_method: 'license-key' | 'user',
    metadata: JSON,
  },
  
  metadata: JSON,
  
  // the following property is only present if is_trial=true
  trial_days: number,
  
  // the following properties is only present if is_floating=true or is_floating_cloud=true
  floating_in_use_devices: number,
  floating_users: number,
  
  // the following properties are only present if license_type='consumption'
  max_consumptions: number,
  total_consumptions: number,
  allow_unlimited_consumptions: boolean,
  reset_consumption: boolean,
  consumption_period: string | null, // string is in DateISO8601UTC format
  
} & ({

  // for key-based licenses:
  license_key: string,

} | {

  // for user-based licenses:
  user: {
    id: number,
    email: string,
    first_name: string,
    last_name: string,
    phone_number: string,
    is_initial_password: boolean,
    max_activations: number,
    allow_unlimited_activations: boolean,
    total_activations: number
  }
});

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "license_key": { "type": "string" }
          },
          "required": ["license_key"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "user": {
              "type": "object",
              "properties": {
                "id": { "type": "number" },
                "email": { "type": "string" },
                "first_name": { "type": "string" },
                "last_name": { "type": "string" },
                "phone_number": { "type": "string" },
                "is_initial_password": { "type": "boolean" },
                "max_activations": { "type": "number" },
                "allow_unlimited_activations": { "type": "boolean" },
                "total_activations": { "type": "number" }
              },
              "required": ["id", "email", "first_name", "last_name", "phone_number", "is_initial_password", "max_activations", "allow_unlimited_activations", "total_activations"],
              "additionalProperties": false
            }
          },
          "required": ["user"],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "id": { "type": "number" },
        "allow_grace_period": { "type": "boolean" },
        "allow_overages": { "type": "boolean" },
        "allow_unlimited_activations": { "type": "boolean" },
        "borrowed_until": { "type": ["string", "null"] },
        "can_borrow": { "type": "boolean" },
        "channel": { "type": "string" },
        "device_id": { "type": "number" },
        "enable_maintenance_period": { "type": "boolean" },
        "environment": { "type": "string" },
        "eula_link": { "type": "string" },
        "floating_timeout": { "type": "number" },
        "grace_period": { "type": "number" },
        "hash_md5": { "type": "string" },
        "installation_file": { "type": "string" },
        "is_air_gapped": { "type": "boolean" },
        "is_borrowed": { "type": "boolean" },
        "is_expired": { "type": "boolean" },
        "is_floating_cloud": { "type": "boolean" },
        "is_floating": { "type": "boolean" },
        "is_hardware_key_auth": { "type": "boolean" },
        "license_active": { "type": "boolean" },
        "license_enabled": { "type": "boolean" },
        "license_signature": { "type": "string" },
        "license_signature_v2": { "type": "string" },
        "offline_signature": { "type": "string" },
        "license_type": { "type": "string" },
        "maintenance_period": { "type": ["string", "null"] },
        "max_activations": { "type": "number" },
        "max_borrow_time": { "type": "number" },
        "max_license_users": { "type": "number" },
        "max_overages": { "type": "number" },
        "max_transfers": { "type": "number" },
        "order_store_id": { "type": "string" },
        "prevent_vm": { "type": "boolean" },
        "release_date": { "type": "string" },
        "release_notes_link": { "type": "string" },
        "requires_version": { "type": "string" },
        "size": { "type": "string" },
        "start_date": { "type": ["string", "null"] },
        "times_activated": { "type": "number" },
        "transfer_count": { "type": "number" },
        "validity_period": { "type": ["string", "null"] },
        "version": { "type": "string" },
        "company": { "type": "object", "properties": {"id": { "type": "number" } } },
        "product_features": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "number" },
              "code": { "type": "string" },
              "name": { "type": "string" },
              "expiry_date": { "type": "string" },
              "metadata": {},
              "feature_type": { "type": "string", "enum": ["activation", "consumption"] },
              "is_floating": { "type": "boolean" },
              "is_floating_cloud": { "type": "boolean" },
              "floating_users": { "type": "number" },
              "floating_timeout": { "type": "number" },
              "max_consumption": { "type": "number" },
              "allow_unlimited_consumptions": { "type": "boolean" },
              "total_consumptions": { "type": "number" },
              "allow_overages": { "type": "number" },
              "max_overages": { "type": "number" },
              "reset_consumption": { "type": "boolean" },
              "consumption_period": {
                "type": ["string", "null"],
                "enum": ["daily", "weekly", "monthly", "annualy", null]
              }
            },
            "required": ["id", "code", "name", "expiry_date", "metadata", "feature_type", "is_floating", "is_floating_cloud"]
          }
        },
        "custom_fields": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "data_type": { "type": "string", "enum": ["numer", "text", "date/time"] },
              "value": { "type": "string" }
            },
            "required": ["name", "data_type", "value"]
          }
        },
        "customer": {
          "type": "object",
          "properties": {
            "email": { "type": "string" },
            "company_name": { "type": "string" },
            "reference": { "type": "string" },
            "phone": { "type": "string" },
            "first_name": { "type": "string" },
            "last_name": { "type": "string" },
            "city": { "type": "string" },
            "postcode": { "type": "string" },
            "state": { "type": "string" },
            "country": { "type": "string" },
            "address": { "type": "string" },
            "customer_account": { "type": ["string", "null"] },
            "metadata": {}
          },
          "required": ["email", "company_name", "reference", "phone", "first_name", "last_name", "city", "postcode", "state", "country", "address", "metadata"]
        },
        "product_details": {
          "type": "object",
          "properties": {
            "product_id": { "type": "number" },
            "product_name": { "type": "string" },
            "short_code": { "type": "string" },
            "authorization_method": { "type": "string", "enum": ["license-key", "user"] },
            "metadata": {}
          },
          "required": ["product_id", "product_name", "short_code", "authorization_method", "metadata"]
        },
        "metadata": {},
        "trial_days": { "type": "number" },
        "floating_in_use_devices": { "type": "number" },
        "floating_users": { "type": "number" },
        "max_consumptions": { "type": "number" },
        "total_consumptions": { "type": "number" },
        "allow_unlimited_consumptions": { "type": "boolean" },
        "reset_consumption": { "type": "boolean" },
        "consumption_period": { "type": ["string", "null"] }
      },
      "required": [
        "id",
        "allow_grace_period",
        "allow_overages",
        "allow_unlimited_activations",
        "can_borrow",
        "channel",
        "device_id",
        "enable_maintenance_period",
        "environment",
        "eula_link",
        "floating_timeout",
        "grace_period",
        "hash_md5",
        "installation_file",
        "is_air_gapped",
        "is_borrowed",
        "is_expired",
        "is_floating_cloud",
        "is_floating",
        "is_hardware_key_auth",
        "license_active",
        "license_enabled",
        "license_signature",
        "license_type",
        "max_activations",
        "max_borrow_time",
        "max_license_users",
        "max_overages",
        "max_transfers",
        "order_store_id",
        "prevent_vm",
        "release_date",
        "release_notes_link",
        "requires_version",
        "size",
        "times_activated",
        "transfer_count",
        "version",
        "product_features",
        "custom_fields",
        "customer",
        "product_details",
        "metadata"
      ],
      "additionalProperties": false
    }
  ]
}

---

Response Signatures

The response objects contain the following digital signatures:

• license_signature — see Response Signature

• license_signature_v2 — see Response Signature v2

• offline_signature — see Deactivate Bundle Offline Method

---

License Authorization Method

There are two types of product licenses based on how the client application authorizes itself to interact with a license:

Key-based product licenses

Each license assigned to the product requires the client to provide a license key in order to activate, check or deactivate the license (property license_key in the request). The license response object will contain the license_key property, and product_details.authorization_method will be "license_key".

User-based product licenses

Each license assigned to the product has a corresponding "license user" instead of a license key. Requires username to be provided. In the license response object, product_details.authorization_method will be "user" and the response object will contain the user object with information on the license user.

---

License Types

The license_type property defines one of the 4 types of licenses based on their duration and how the license is used:

• perpetual: "perpetual"

• time-limited: "time-limited"

• subscription: "subscription"

• consumption: "consumption"

For more information see: License Types

---

Errors

If an error occurs, the response will have an HTTP status code of 400 or higher, and the response body will contain an error description in the following format:

Error schema (TypeScript + JSON Schema)

{
  status: number,
  code: string,
  message: string
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}

List of exceptions

missing_headers (400)

Some headers are missing

unknown_product (400)

Provided product was not found

license_not_found (400)

License with the provided license user not found

license_not_enabled (400)

The license is not enabled

license_not_active (400)

The license is not active

device_not_found (400)

An active device matching the hardware_id not found

blacklisted (400)

This device is blacklisted

license_not_enough_consumptions (400)

Not enough consumptions left

floating_not_available (400)

No available slots for floating license