# Trial Key

### Endpoint

* Method: `GET`
* Path: `/api/v4/trial_key`
* Description: Creates and returns a trial license.

### Authentication

See [License API Authorization](https://docs.licensespring.com/license-api/license-api-authorization).

#### Required headers

* `Date` (string)
* `Authorization` (string)

#### Recommended headers

* `Accept: application/json`

### Request

#### Query parameters

Required:

* `hardware_id` (string)
* `product` (string)

Optional (user-based products):

* `email` (string)
* `password` (string)
* `first_name` (string)
* `last_name` (string)
* `phone` (string)

Optional:

* `license_policy` (string)
* customer metadata fields (`address`, `postcode`, `state`, `country`, `city`, `reference`)

<details>

<summary><strong>Interactive reference (raw)</strong></summary>

:::note

```json
{
  "tab": "examples",
  "url": "/api/v4/trial_key",
  "name": "/api/v4/trial_key ",
  "method": "GET",
  "request": {
    "pathParameters": [],
    "queryParameters": [
      {
        "kind": "required",
        "name": "hardware_id",
        "type": "string",
        "children": [],
        "description": "In RFC7231 format (see \"License API Authorization\"), eg.: Thu, 17 Nov 2022 20:51:35 GMT"
      },
      {
        "kind": "required",
        "name": "product",
        "type": "string",
        "children": [],
        "description": "Product short code"
      },
      {
        "kind": "optional",
        "name": "email",
        "type": "string",
        "children": [],
        "description": "Required if product is user based. Attach the assigned license user email (eq. user@example.com)"
      },
      {
        "name": "license_policy",
        "kind": "optional",
        "type": "string",
        "description": "Sets license policy (license policy code), if omited the default license policy for the product will be used",
        "children": []
      },
      {
        "name": "first_name",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "last_name",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "phone",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "password",
        "kind": "optional",
        "type": "string",
        "description": "Only for user-based licenses: Sets the license user's password. If not provided, a random password will be generated and returned in the response",
        "children": []
      }
    ],
    "headerParameters": [
      {
        "kind": "required",
        "name": "Date",
        "type": "string",
        "children": [],
        "description": "In RFC7231 format (see \"License API Authorization\"), eg.: Thu, 17 Nov 2022 20:51:35 GMT"
      },
      {
        "kind": "required",
        "name": "Authorization",
        "type": "string",
        "children": [],
        "description": "See \"License API Authorization\" article"
      }
    ],
    "bodyDataParameters": [],
    "formDataParameters": []
  },
  "results": {
    "languages": [
      {
        "id": "QLX3IFr3FPKeqNnhkuAXk",
        "code": "{\n    \"license_key\": \"T7GB-C4JX-4Y8R-1234\",\n    \"id\": 1737130277841509,\n    \"order_id\": 1737130277837489,\n    \"product_id\": 1,\n    \"created_at\": 1737130277925,\n    \"updated_at\": 1737130277925,\n    \"max_activations\": 1,\n    \"times_activated\": 0,\n    \"is_trial\": true,\n    \"active\": false,\n    \"enabled\": true,\n    \"trial_days\": 15,\n    \"license_type\": \"time-limited\",\n    \"max_transfers\": 0,\n    \"prevent_vm\": false,\n    \"enable_maintenance_period\": false,\n    \"maintenance_duration\": null,\n    \"metadata\": {},\n    \"is_hardware_key_auth\": false,\n    \"validity_period\": null,\n    \"LicenseProductFeatures\": [\n        {\n            \"id\": \"1737130277926519\",\n            \"product_feature_id\": 5,\n            \"max_consumption\": 10,\n            \"allow_overages\": false,\n            \"max_overages\": 0,\n            \"reset_consumption\": false,\n            \"consumption_period\": null,\n            \"expiry_date\": null,\n            \"metadata\": {},\n            \"is_floating\": false,\n            \"is_floating_cloud\": false\n        }\n    ],\n    \"LicenseCustomFields\": [],\n    \"license\": \"T7GB-C4JX-4Y8R-1234\"\n}",
        "language": "200",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "QLX3IFr3FPKeqNnhkuAXk"
  },
  "examples": {
    "languages": [
      {
        "id": "GCdqGE3Uarg-ovc11AFKF",
        "language": "curl",
        "code": "curl --location --request GET '/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string' \\\n--header 'Accept: application/json' \\\n--header 'Date: string' \\\n--header 'Authorization: string'",
        "customLabel": ""
      },
      {
        "id": "kVmRuRWFg1WdVHBr_jJsI",
        "language": "nodejs",
        "code": "var request = require('request');\nvar options = {\n   'method': 'GET',\n   'url': '/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string',\n   'headers': {\n      'Accept': 'application/json',\n      'Date': 'string',\n      'Authorization': 'string'\n   }\n};\nrequest(options, function (error, response) {\n   if (error) throw new Error(error);\n   console.log(response.body);\n});\n",
        "customLabel": ""
      },
      {
        "id": "VzSNg-xq9B50TtFX7fGlE",
        "language": "javascript",
        "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\nmyHeaders.append(\"Date\", \"string\");\nmyHeaders.append(\"Authorization\", \"string\");\n\nvar requestOptions = {\n   method: 'GET',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));",
        "customLabel": ""
      },
      {
        "id": "FANx6WPBmq3niAudJgpuM",
        "language": "python",
        "code": "import requests\n\nurl = \"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\"\n\npayload={}\nheaders = {\n   'Accept': 'application/json',\n   'Date': 'string',\n   'Authorization': 'string'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
        "customLabel": ""
      },
      {
        "id": "Z5q0sg9XmQTNVHKXuCjN_",
        "language": "ruby",
        "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Get.new(url)\nrequest[\"Accept\"] = \"application/json\"\nrequest[\"Date\"] = \"string\"\nrequest[\"Authorization\"] = \"string\"\n\nresponse = http.request(request)\nputs response.read_body\n",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "FANx6WPBmq3niAudJgpuM"
  },
  "description": "Creates and returns a trial license",
  "currentNewParameter": {
    "label": "Query Parameter",
    "value": "queryParameters"
  }
}
```

:::

</details>

{% hint style="danger" %}
For a trial license to be created, the product must have trial licenses enabled by setting `allow_trial` to true.

By default, the same combination of hardwareID and product will generate the same trial key. This ensures that users cannot obtain multiple trial keys on the same device.

If you want to permit multiple trial licenses on the same device, you can enable this feature by adjusting the **Allow multiple licenses on trial** setting in the vendor platform under your company account settings.
{% endhint %}

### Schema

#### Request Query Parameters

```typescript
type TrialKeyRequestParameters = {
  
  // required parameters:
  product: string,
  hardware_id: string,
  
  // required for user-based products:
  email?: string | undefined,
  
  // optional for user-based products:
  password?: string | undefined,
  
  // optional property:
  license_policy?: string | undefined,
  
  // if any of the following optional properties is set, a Customer is created for (or associated to) this Trial Key request:
  first_name?: string | undefined,
  last_name?: string | undefined,
  phone?: string | undefined,
  address?: string | undefined,
  postcode?: string | undefined,
  state?: string | undefined,
  country?: string | undefined,
  city?: string | undefined,
  reference?: string | undefined,
}
```

JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": { "type": "string" },
    "hardware_id": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": ["string"] },
    "license_policy": { "type": ["string"] },
    "first_name": { "type": ["string"] },
    "last_name": { "type": ["string"] },
    "phone": { "type": ["string"] },
    "address": { "type": ["string"] },
    "postcode": { "type": ["string"] },
    "state": { "type": ["string"] },
    "country": { "type": ["string"] },
    "city": { "type": ["string"] },
    "reference": { "type": ["string"] }
  },
  "oneOf": [
    { "required": ["product", "hardware_id"] },
    { "required": ["product", "hardware_id", "email"] }
  ],
  "additionalProperties": false
}
```

#### Response Body

{% hint style="info" %}
The response from this endpoint will differ depending in whether a trial license already exists for the requested product, hardware ID and email\* (\*if using user-based license)
{% endhint %}

{% stepper %}
{% step %}

### If a new trial license is being created

```typescript
type TrialKeyResponseBody = {

  id: number,
  license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
  order_id: number,
  product_id: number,
  max_activations: number,
  times_activated: number,
  is_trial: true,
  active: boolean,
  enabled: boolean,
  max_transfers: number,
  trial_days: number,
  maintenance_duration: string | null, // Length of time expressed in days, months or years, e.g. 5d, 2m, 3y
  validity_period: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
  enable_maintenance_period: boolean,
  prevent_vm: boolean,
  is_hardware_key_auth: boolean,
  initial_password: string,
  metadata: JSON,
  created_at: number, // UNIX Timestamp in milliseconds
  updated_at: number, // UNIX Timestamp in milliseconds
  
  LicenseProductFeatures: ({
    id: number,
    product_feature_id: number,
    max_consumption: number,
    allow_overages: boolean,
    max_overages: number,
    reset_consumption: number,
    consumption_period: string | null,
    expiry_date: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
    is_floating: boolean,
    is_floating_cloud: boolean,
    metadata: JSON,
    
    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_timeout: number,
    floating_users: number,
  })[],
  
  LicenseCustomFields: {
    product_custom_field_id: number,
    value: string
  }[],
  
  // the following properties are only present for key-based product licenses
  license: string,
  license_key: string,
  
  // the following properties are only present for user-based product licenses
  license_user: string,
  initial_password: string,
  max_license_users: number,
  license_user_id: number | null,
  
  // the following properties are only present if license_type="subscription"
  grace_period: number,
  allow_grace_period: boolean,
  
  // the following properties are only present if license_type="consumption"
  allow_overages: boolean,
  max_overages: number,
  max_consumptions: number,
  valid_duration: null,
  consumption_period: string | null,
  reset_consumption: boolean,
}
```

{% endstep %}

{% step %}

### If a trial license already exists

```typescript
{
    license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
    is_trial: true,
    
    // the following property is only present on key-based product licenses
    license: string,
    
    // the following property is only present on user-based product licenses
    license_user: string,
}
```

{% endstep %}
{% endstepper %}

### Examples

{% tabs %}
{% tab title="curl" %}

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

{% endtab %}

{% tab title="nodejs" %}

```javascript
var request = require('request');
var options = {
  method: 'GET',
  url: '/api/v4/trial_key?hardware_id=string&product=string',
  headers: {
    'Accept': 'application/json',
    'Date': 'string',
    'Authorization': 'string'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

{% endtab %}

{% tab title="javascript (fetch)" %}

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("/api/v4/trial_key?hardware_id=string&product=string", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "/api/v4/trial_key?hardware_id=string&product=string"

headers = {
  "Accept": "application/json",
  "Date": "string",
  "Authorization": "string"
}

response = requests.get(url, headers=headers)
print(response.text)
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require "uri"
require "net/http"

url = URI("/api/v4/trial_key?hardware_id=string&product=string")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"

response = http.request(request)
puts response.read_body
```

{% endtab %}
{% endtabs %}

### 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:

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

JSON Schema

```json
{
  "$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\_parameters** (400): Some parameters are missing in the request: { params }

> **missing\_hardware\_id** (400): The hardware\_id missing in the request

> **unknown\_product** (400): Provided product was not found

> **trial\_not\_allowed** (400): Product does not allow trial

> **email\_missing** (400): An email is missing for user-based product