# JSON File Reference

> The Things Stack has support for importing end devices from JSON files.

Source: https://www.thethingsindustries.com/docs/hardware/devices/adding-devices/adding-devices-in-bulk/device-json/


The Things Stack has support for importing end devices from JSON files.

This method is useful when batches of end devices are managed as JSON files or to add end devices in bulk from V2, ChirpStack and other LoRaWAN® networks using a JSON file describing those devices.

Using JSON file with device descriptions, you can migrate end devices with or without their existing sessions.

Here is an example of an OTAA device description in the `devices.json` file:

```json
{
  "ids": {
    "device_id": "my-device",
    "dev_eui": "0102030405060708",
    "join_eui": "0102030405060708"
  },
  "name": "My Device",
  "description": "Living room temperature sensor",
  "lorawan_version": "MAC_V1_0_2",
  "lorawan_phy_version": "PHY_V1_0_2_REV_B",
  "frequency_plan_id": "EU_863_870_TTN",
  "supports_join": true,
  "root_keys": {
    "app_key": {
      "key": "01020304050607080102030405060708"
    }
  }
}
```

Multiple end devices can also be contained in a single `devices.json` file like so:

```js
{
  /* device 1 */
}
{
  /* device 2 */
}
```

The format above is considered by the Console and CLI as a JSON stream, processing one object at a time.
For more details in how to use the file, please refer to [Adding End Devices in Bulk](https://www.thethingsindustries.com/docs/hardware/devices/adding-devices/adding-devices-in-bulk/).

## JSON End Device Format

The full specification of the JSON format is defined in the API protos. See the [EndDevice](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#message:EndDevice) message definition for details.

The linked specification is quite extensive, and contains a lot of fields that are not required, or are only set and used internally by the Network Server. Below, the required and most commonly used fields are discussed.

<div class="table-device-json">

| Field                                    | Required                 | Type    | Example                              | Description                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------- | ------------------------ | ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`ids.device_id`**                      | **Always**               | string  | `"sensor-1"`                         | [More info](https://www.thethingsindustries.com/docs/getting-started/glossary/#device-id)                                                                                                                                                                                                                                                                                                         |
| **`ids.dev_eui`**                        | **Always**               | string  | `"0102030405060708"`                 | [More info](https://www.thethingsindustries.com/docs/getting-started/glossary/#deveui)                                                                                                                                                                                                                                                                                                            |
| **`ids.join_eui`**                       | **Always**               | string  | `"0102030405060708"`                 | Also referred to as **AppEUI**. [More info](https://www.thethingsindustries.com/docs/getting-started/glossary/#joineui)                                                                                                                                                                                                                                                                           |
| **`name`**                               | No                       | string  | `"My Sensor"`                        | Optional, a name for the device                                                                                                                                                                                                                                                                                                                                        |
| **`description`**                        | No                       | string  | `"Situated in living room"`          | Optional, description of the device                                                                                                                                                                                                                                                                                                                                    |
| **`lorawan_version`**                    | **Always**               | string  | `"MAC_V1_0_2"`                       | See [MACVersion](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#enum:MACVersion) for supported versions. See [LoRaWAN Version](https://www.thethingsindustries.com/docs/getting-started/glossary/#lorawan-version) for more information.                                                                                                                                                            |
| **`lorawan_phy_version`**                | **Always**               | string  | `"PHY_V1_0_2_REV_B"`                 | See [PHYVersion](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#enum:PHYVersion) for supported versions. See [LoRaWAN Version](https://www.thethingsindustries.com/docs/getting-started/glossary/#regional-parameters) for more information.                                                                                                                                                        |
| **`frequency_plan_id`**                  | **Always**               | string  | `"EU_863_870_TTN"`                   | See [Frequency Plans](https://www.thethingsindustries.com/docs/concepts/features/lorawan/frequency-plans/) for a list of supported frequency plans (The frequency plan `ID` is needed). See [Frequency Plan](https://www.thethingsindustries.com/docs/getting-started/glossary/#frequency-plan) for more information.                                                                                                        |
| **`supports_join`**                      | No                       | boolean | `true`                               | `true` for OTAA devices, `false` for ABP. Defaults to `false` (ABP) if not set.                                                                                                                                                                                                                                                                                        |
| **`supports_class_c`**                   | No                       | boolean | `true`                               | `true` for Class C devices, `false` otherwise.                                                                                                                                                                                                                                                                                                                         |
| **`root_keys.app_key.key`**              | **For OTAA devices**     | string  | `"01020304050607080102030405060708"` | See [Application Key](https://www.thethingsindustries.com/docs/getting-started/glossary/#application-key) for more information.                                                                                                                                                                                                                                                                   |
| **`root_keys.nwk_key.key`**              | **For OTAA devices**     | string  | `"01020304050607080102030405060708"` | For LoRaWAN version 1.1 and later only. See [Network Key](https://www.thethingsindustries.com/docs/getting-started/glossary/#network-key) for more information.                                                                                                                                                                                                                                   |
| **`mac_settings.rx1_delay`**             | No                       | string  | `"RX_DELAY_5"`                       | Delay for the first Class A receive window (Rx1). Typical values are `"RX_DELAY_1"` (1 second) and `"RX_DELAY_5"` (5 seconds). See [MACSettings](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#message:MACSettings) for more information.                                                                                                                               |
| **`mac_settings.supports_32_bit_f_cnt`** | No                       | boolean | `false`                              | `true` if device supports 32-bit frame counters, `false` if device only supports 16-bit frame counters.                                                                                                                                                                                                                                                                |
| **`session.dev_addr`**                   | **For existing session** | string  | `"01020304"`                         | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Device Address](https://www.thethingsindustries.com/docs/getting-started/glossary/#device-address) for more information.                                                                                                                                                                                 |
| **`session.keys.app_s_key.key`**         | **For existing session** | string  | `"01020304050607080102030405060708"` | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Application Session Key](https://www.thethingsindustries.com/docs/getting-started/glossary/#application-session-key) for more information.                                                                                                                                                               |
| **`session.keys.f_nwk_s_int_key.key`**   | **For existing session** | string  | `"01020304050607080102030405060708"` | Forwarding Network Session Integrity Key, also referred to as **Network Session Key** in LoRaWAN v1.0.x compatibility mode. See [SessionKeys](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#message:SessionKeys) and [Forwarding Network Session Integrity Key](https://www.thethingsindustries.com/docs/getting-started/glossary/#forwarding-network-session-integrity-key) for more information. |
| **`session.keys.session_key_id`**        | **For existing session** | string  | `"AXA50tHhzVMGEE…"`                 | A unique identifier for the session keys. If not provided, generate a random 16-byte value and encode it using base64. Required when importing devices via the Console.                                                                                                                                                                                                |
| **`session.last_f_cnt_up`**              | **For existing session** | uint    | `12`                                 | Last uplink frame counter used.                                                                                                                                                                                                                                                                                                                                        |
| **`session.last_n_f_cnt_down`**          | **For existing session** | uint    | `12`                                 | Last network downlink frame counter used.                                                                                                                                                                                                                                                                                                                              |
| **`session.last_a_f_cnt_down`**          | **For existing session** | uint    | `12`                                 | Last application downlink frame counter used.                                                                                                                                                                                                                                                                                                                          |

</div>
<br>

Note that the dots in the **Field** column imply an embedded object. For example, `root_keys.nwk_key.key` must be set as:

```
"root_keys": {
  "nwk_key:": {
  "key": "<NWK_KEY_HERE>"
  }
}
```

