Swif allows you to manage custom device metadata—called extension attributes—using a powerful webhook API. This guide will show you how to set, update, and delete extension attributes for your devices programmatically.

Prerequisites

API Key: You’ll need your Swif API key. Find instructions here: How to get your API key
Base URL: Replace {{base_url}} with https://api.swifteam.com.

API Endpoints

1. Retrieve Extension Attributes

GET

{{base_url}}/restful/organization/deviceExtensionAttributes?ids=<device_id>&offset=0&limit=10

Example:

GET {{base_url}}/restful/organization/deviceExtensionAttributes?ids=69114f7534000025006e720e&offset=0&limit=10

2. Set or Update Extension Attributes

POST

{{base_url}}/restful/organization/deviceExtensionAttributes?ids=<device_id>

Body Example:

{
  "items": [
    {
      "deviceId": "69114f7534000025006e720e",
      "attributes": [
        {
          "key": "owner",
          "value": "alice@example.com"
        },
        {
          "key": "disk_size_gb",
          "value": "512"
        }
      ]
    }
  ]
}

To update an attribute: Provide the key and a non-empty value.
To delete an attribute: Provide the key with an empty string or null as the value (see below for behavior).

3. Delete Extension Attributes

DELETE

{{base_url}}/restful/organization/deviceExtensionAttributes

Body Example:

{
  "deviceIds": [
    "69114f7534000025006e720e"
  ],
  "keys": [
    "owner",
    "assetTag"
  ]
}

Behavior and Test Scenarios

The webhook API is designed to be robust and intuitive. Here’s how it behaves in common scenarios:

Scenario	What Happens?
Set Attribute	Sending a non-empty value sets or updates the attribute for the device.
Delete Attribute (Empty/Null Value)	Sending an empty string or `null` as the value deletes the attribute. No error is returned; the attribute is simply removed.
No Attribute Present, Empty/Null Value	If the attribute does not exist and you send an empty/null value, nothing happens—no attribute is created.
Bulk Ingestion (Mixed Values)	For each device/attribute: non-empty values are set/updated; empty/null values are deleted.
All Empty/Null	All specified attributes are deleted for the listed devices.
All Non-Empty	All specified attributes are set/updated for the listed devices.
Unknown Key	If you send a key not present in your schema, it is ignored or rejected. You’ll receive an error: `"errorMessage": "We could not match this attribute key to any extension attribute definition."`
Invalid Value Type	`"errorMessage": "We received this attribute but rejected it because the data format does not match the definition (e.g. a number was sent for a Boolean)."`
Explicit Removal	You can remove an attribute by sending an empty string, `null`, or using the DELETE endpoint.

Example: Setting and Deleting Attributes

Set or Update:

curl --location 'https://api.swifteam.com/restful/organization/deviceExtensionAttributes?ids=69114f7534000025006e720e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "items": [
        {
            "deviceId": "69114f7534000025006e720e",
            "attributes": [
                {
                    "key": "owner",
                    "value": "alice@example.com"
                },
                {
                    "key": "disk_size_gb",
                    "value": "512"
                }
            ]
        }
    ]
}'

Delete (by empty value):

curl --location 'https://api.swifteam.com/restful/organization/deviceExtensionAttributes?ids=69114f7534000025006e720e' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
  "items": [
    {
      "deviceId": "69114f7534000025006e720e",
      "attributes": [
        { "key": "owner", "value": "" }
      ]
    }
  ]
}'

Delete (by DELETE endpoint):

curl --location --request DELETE 'https://api.swifteam.com/restful/organization/deviceExtensionAttributes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
    "deviceIds": [
        "69114f7534000025006e720e"
    ],
    "keys": [
        "owner",
        "assetTag"
    ]
}'

Tips

Always check your attribute schema for valid keys and value types.
Use the GET endpoint to verify changes after webhook calls.
For bulk operations, you can include multiple devices and attributes in a single request.

More Information

By following this guide, you can efficiently automate the management of device extension attributes in Swif using webhooks. If you encounter errors, refer to the error messages for troubleshooting or reach out to support.

[APIs] Device and evidence retrieval

How to run Commands as Administrator on Windows devices with Swif

Installing Custom Software via Swif

How to Retrieve and Save Linux Device Encryption Recovery Keys in Swif

How to Configure Swif.ai RADIUS Wi-Fi Policy Using SCEPman as the SCEP Certificate Provider

How to Edit Device Extension Attributes via Webhook API