List Connected Accounts

Get all Connected accounts

Returns a list of all connected accounts.

/connected_accounts/list

POSThttps://connect.getseam.com/connected_accounts/list

Authorization

api_keypat_with_workspaceconsole_session_with_workspace

Body

application/json

user_identifier_keystring

Returns accounts that can be accessed by the provided user_identifier_key.

custom_metadata_hasobject

Returns accounts whose custom_metadata contains all of the provided key/value pairs.

Response

200400401

OK

Body

application/json

connected_accounts*array of connected_account (object)

ok*boolean

Request

JavaScriptCurlPython

const response = await fetch('https://connect.getseam.com/connected_accounts/list', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer API Key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "connected_accounts": [
    {
      "connected_account_id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-01-20T18:50:53.291Z",
      "user_identifier": {
        "username": "text",
        "api_url": "text",
        "email": "text",
        "phone": "text",
        "exclusive": false
      },
      "account_type": "text",
      "account_type_display_name": "text",
      "errors": [
        {
          "message": "text",
          "is_connected_account_error": true,
          "error_code": "account_disconnected"
        }
      ],
      "warnings": [
        {
          "message": "text",
          "warning_code": "scheduled_maintenance_window"
        }
      ],
      "automatically_manage_new_devices": false
    }
  ],
  "ok": false
}

Request

To filter the list of returned connected accounts by a specific set of custom metadata or a user identifier key, include custom_metadata_has or user_identifier_key in the request body. If you include custom_metadata_has, specify the desired metadata filters as a JSON object containing key:value pairs.

Request Body Parameters

Parameter	Type	Description
user_identifier_key	String Optional	The internal user ID (your own internal ID for a user) by which you want to filter connected accounts.
custom_metadata_has	JSON object Optional	Set of key:value custom metadata pairs by which you want to filter connected accounts. For more information, see Adding Custom Metadata to Connected Accounts.

Sample Request

Python

connected_accounts = seam.connected_accounts.list()

cURL (bash)

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/connected_accounts/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{}'

Javascript

await seam.connectedAccounts.list();

Ruby

seam.connected_accounts.list()

PHP

$connected_accounts = $seam->connected_accounts->list();
echo json_encode($connected_accounts);

Response

Returns a connected_accounts array, in which each returned connected_account contains the following properties:

Property	Description
connected_account_id	ID of the connected account
created_at	Date and time at which the connected account was created
user_identifier	Unique identifier for the connected account, such as an email address or phone number
account_type	Type of manufacturer to which the connected account belongs, such as august, schlage, yale, salto, smartthings, and so on
account_type_display_name	Version of account_type that can be displayed in a user interface
custom_metadata	Set of custom_metadata set on the Connect Webview that connected the account. You can also modify or add to this custom_metadata.
automatically_manage_new_devices	Indicates whether Seam should import all new devices for the connected account to make these devices available for use and management by the Seam API. You initially specify the value for this property when creating the corresponding Connect Webview.

Sample Response

JSON

{
  "connected_accounts": [
    {
      "connected_account_id": "c993818b-bf3c-4836-bef4-9a76d89bf1d3",
      "created_at": "2024-01-05T07:20:07.692Z",
      "user_identifier": {
        "username": "jane"
      },
      "account_type": "visionline",
      "account_type_display_name": "Visionline",
      "errors": [],
      "warnings": [],
      "custom_metadata": {
          "internal_account_id": "user-1"
      },
      "automatically_manage_new_devices": true
    },
	...
  ],
  "ok": true
}