Documentation

Copy page

Connect API - Shelly Device Onboarding

TL;DR

• Shelly uses the form flow — collect the user's Shelly Cloud auth key and POST it as connection data
• A Shelly device's model.category determines its type: smart plugs / relays (e.g. Plug S, 1PM, 2PM) are switch and controllable via on-off; EM / 3EM energy meters (e.g. Shelly EM, 3EM, Pro 3EM, EM Gen3) are electricMeter and used for metering only (no on-off)
• Only the electricMeter (EM / 3EM) variants require measurement-purpose via PUT /devices/{id}/measurement-purpose (gridMeter or pvProduction) — otherwise setup stays incomplete. pvProduction re-creates the device as a producing switch that reports PV output but is still not on-off-controllable
• One Shelly Cloud account = one integrator = one connection. All Shelly devices under that account appear in the device list

Complete flow for connecting Shelly devices via the Connect API.

---

Step 1: List Vendors

Code
GET /v1/users/{userId}/vendors

Response:

Code
{
  "data": [
    {
      "id": "85aa4cd1-2949-41be-a227-ce4bfe281e24",
      "name": "BMW"
    },
    {
      "id": "ce1332aa-5d51-4222-8b4a-f759862b3ced",
      "name": "Home Connect"
    },
    {
      "id": "f8c2e4a1-9b3d-4f7c-8a1e-2d5f6c9b4a3e",
      "name": "Shelly"
    },
    {
      "id": "c36018d3-334e-4d44-82b9-324f2ff7de41",
      "name": "Solvis"
    },
    {
      "id": "ae1b4468-217e-440d-a2c7-3c44d283a6c1",
      "name": "Tesla"
    },
    {
      "id": "09527b83-6665-4202-9666-a59840ef3a27",
      "name": "Vaillant"
    },
    {
      "id": "e591b6fb-9fdc-4283-ade9-d16266572882",
      "name": "Viessmann"
    },
    {
      "id": "32630d0a-467b-4f8f-8dd0-b417e78a0b70",
      "name": "Volkswagen"
    }
  ]
}

---

Step 2: Get Connection Options

Code
GET /v1/users/{userId}/vendors/{vendorId}/connection-options

For Shelly (vendorId: f8c2e4a1-9b3d-4f7c-8a1e-2d5f6c9b4a3e):

Response:

Code
{
  "flow": "form",
  "formOptions": [
    {
      "type": "login",
      "data": {
        "url": "https://my.shelly.cloud/integrator.html?itg=ITG_CPV1&cb=https%3a%2f%2ffa-cpv-shelly-itg-beta.azurewebsites.net%2fapi%2fShellyIntegrator%3fcode%3d6eUTCK1JBN8PA6khvwwagXb_27G6g0gd9O1raM4wcNEVAzFumTTRvg%3d%3d%26userid%3d76508964-f720-479d-9c6e-5f1c51b1d6bc"
      }
    }
  ],
  "docUrl": null
}

The Shelly integration uses a "form" flow with a "login" type. This means you'll need to open the provided URL in a browser or WebView for user authentication.

---

Step 3: Create Connection

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

Request:

Code
{
  "type": "form",
  "data": {  }
}

Response:

Code
{
  "connectionId": "<CONNECTION_ID>",
  "vendorId": "f8c2e4a1-9b3d-4f7c-8a1e-2d5f6c9b4a3e"
}

---

Step 4: User Interaction

After creating the connection, guide the user through the Shelly integrator:

1. Open browser/WebView to the URL from Step 2: https://my.shelly.cloud/integrator.html?itg=ITG_CPV1&cb=https%3a%2f%2ffa-cpv-shelly-itg-beta.azurewebsites.net%2fapi%2fShellyIntegrator%3fcode%3d6eUTCK1JBN8PA6khvwwagXb_27G6g0gd9O1raM4wcNEVAzFumTTRvg%3d%3d%26userid%3d76508964-f720-479d-9c6e-5f1c51b1d6bc
2. User logs in with their Shelly account.
3. User clicks the device to pair from the device list.
4. Authorize the integrator on the device-detail screen by performing all three of these actions:
   1. Under the label "ENABLE INTEGRATOR FOR THIS DEVICE", tap the "YES" button.
   2. Under the label "ALLOW DEVICE CONTROL", tap the "YES" button.
   3. Tap the "SAVE" button at the bottom of the screen.
5. On success, the Shelly UI shows a "Done" alert. The user can close the tab afterwards. The devices are then pushed by Shelly to our backend and will appear in the next step.

---

Step 5: List Devices from Vendor

Code
GET /v1/users/{userId}/vendors/{vendorId}/devices?connectionId={connectionId}

Response:

Code
{
  "data": [
    {
      "name": "Office",
      "text": "<SHELLY_DEVICE_ID>",
      "model": {
        "id": "a5bcf4ef-9ad9-4183-9c60-5a1dcae3917b",
        "name": "Shelly Plus Plug S",
        "category": "switch"
      },
      "externalId": "<SHELLY_DEVICE_ID>",
      "available": true,
      "connectionId": "<CONNECTION_ID>"
    }
  ]
}

---

Step 6: Create Device in Connect API

Code
POST /v1/users/{userId}/devices

Request:

Code
{
  "name": "Shelly Office in clever-PV",
  "externalId": "<SHELLY_DEVICE_ID>",
  "modelId": "a5bcf4ef-9ad9-4183-9c60-5a1dcae3917b",
  "connectionId": "<CONNECTION_ID>"
}

Response:

Code
{
  "id": "<DEVICE_ID>",
  "name": "Shelly Office in clever-PV",
  "externalId": "<SHELLY_DEVICE_ID>",
  "model": {
    "id": "a5bcf4ef-9ad9-4183-9c60-5a1dcae3917b",
    "name": "ShellyPlusPlugS",
    "category": "switch",
    "vendor": {
      "id": "f8c2e4a1-9b3d-4f7c-8a1e-2d5f6c9b4a3e",
      "name": "Shelly"
    }
  },
  "capabilities": [
    {
      "name": "core",
      "data": {
        "name": "Office in clever-PV",
        "connectivityStatus": "online"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "display-power",
      "data": {
        "power": null,
        "lastUpdate": null
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "on-off",
      "data": {
        "state": "off"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "preferred-operating-mode",
      "data": {
        "mode": "smartControl"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "price-control",
      "data": {
        "enabled": false,
        "threshold": 25
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "priority",
      "data": {
        "priority": 1
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "rated-capacity",
      "data": {
        "ratedCapacity": 100
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "smart-mode",
      "data": {
        "enabled": false
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "solar-optimization",
      "data": {
        "enabled": false,
        "ratedCapacity": 100,
        "sunShare": 100
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "switch-delay",
      "data": {
        "switchDelayOn": 0,
        "switchDelayOff": 0
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "target-control",
      "data": {
        "enabled": false,
        "targetControlLock": null,
        "currentRuntime": 0,
        "hasReachedTarget": false,
        "lastTargetControl": null,
        "startTime": null,
        "endTime": null,
        "targetRuntime": null,
        "startDate": null,
        "endDate": null,
        "weekDays": null,
        "type": null,
        "useSmartChargePlan": null,
        "sendPushNotification": null,
        "enableTargetControlLimit": null,
        "lastUpdate": null
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "time-control",
      "data": {
        "nextSchedule": null
      },
      "options": null,
      "interventions": []
    }
  ]
}

---

Step 7: Control Device (Turn Switch On/Off)

Code
PUT /v1/users/{userId}/devices/{deviceId}/on-off

Request (Turn On):

Code
  {
    "state": "on"
  }

Request (Turn Off):

Code
  {
    "state": "off"
  }

Response: 202

---

Step 8: Get Device Status

Retrieve the device with current power load and state:

Code
GET /v1/users/{userId}/devices/{deviceId}

Response:

Code
{
  "id": "<DEVICE_ID>",
  "name": "Office in clever-PV",
  "externalId": "<SHELLY_DEVICE_ID>",
  "model": {
    "id": "a5bcf4ef-9ad9-4183-9c60-5a1dcae3917b",
    "name": "ShellyPlusPlugS",
    "category": "switch",
    "vendor": {
      "id": "f8c2e4a1-9b3d-4f7c-8a1e-2d5f6c9b4a3e",
      "name": "Shelly"
    }
  },
  "capabilities": [
    {
      "name": "core",
      "data": {
        "name": "Office in clever-PV 3",
        "connectivityStatus": "online"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "display-power",
      "data": {
        "power": 912,
        "lastUpdate": "2025-12-11T13:12:24Z"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "on-off",
      "data": {
        "state": "on"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "preferred-operating-mode",
      "data": {
        "mode": "smartControl"
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "price-control",
      "data": {
        "enabled": false,
        "threshold": 25
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "priority",
      "data": {
        "priority": 1
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "rated-capacity",
      "data": {
        "ratedCapacity": 100
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "smart-mode",
      "data": {
        "enabled": false
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "solar-optimization",
      "data": {
        "enabled": false,
        "ratedCapacity": 100,
        "sunShare": 100
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "switch-delay",
      "data": {
        "switchDelayOn": 0,
        "switchDelayOff": 0
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "target-control",
      "data": {
        "enabled": false,
        "targetControlLock": null,
        "currentRuntime": 0,
        "hasReachedTarget": false,
        "lastTargetControl": null,
        "startTime": null,
        "endTime": null,
        "targetRuntime": null,
        "startDate": null,
        "endDate": null,
        "weekDays": null,
        "type": null,
        "useSmartChargePlan": null,
        "sendPushNotification": null,
        "enableTargetControlLimit": null,
        "lastUpdate": null
      },
      "options": null,
      "interventions": []
    },
    {
      "name": "time-control",
      "data": {
        "nextSchedule": null
      },
      "options": null,
      "interventions": []
    }
  ]
}

Note the display-power capability now shows the current power consumption (power: 912 watts) and when it was last updated.