Device Account Transfer Workflow

Devices can be owned by one account at a time. A device can be transferred from one account to another.

Use Case

1. Business Systems can implicitly transfer (no-approval) a device to a Dealer account, either immediately or scheduled for a future date
2. Dealer with an established business relationship can implicitly transfer a device to a Customer account, either immediately or scheduled for a future date
3. Dealer wants to initiate transfer of a device to a Customer account (without business relationship) and Customer can approve/reject the request

Authorization

• Subjects need device-transfer role on their account to initiate and approve/reject transfer requests
• Only privileged applications can search for devices across accounts and perform implicit transfer
• Dealers with an established doingBusinessWith relationship can also perform implicit transfers (without approval) to/from their customers

Prerequisites

• Create a device in an account using POST device API spec. The device will be created in the account of the calling subject

Steps

Implicit Transfer

Implicit transfer can be performed in two scenarios:

1. Privileged Applications: Only privileged applications can search for devices across accounts and perform implicit transfers. If you have such requirements, contact IAM team with business justification.
2. Dealer-Customer Business Relationship: Dealers with an established doingBusinessWith relationship can implicitly transfer devices to/from their customers. See Dealer to Customer Implicit Transfer for details.

Both scenarios support immediate and scheduled transfers.

Opting into the approval workflow (requireApproval)

If the caller would normally qualify for an implicit transfer but you require the target account to explicitly approve or reject the request, set the query parameter requireApproval=true on POST /devices/{deviceId}/transfer.

Do not include startDate(Scheduled Transfer) in the JSON body when requireApproval=true.

POST {base URL}/devices/{deviceId}/transfer?requireApproval=true

Request body:

{
  "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1"
}

The transfer then follows the approval workflow (for example status PENDING until the recipient approves or rejects), not an immediate or scheduled implicit transfer.

• Use the Search API to search for devices across accounts using either

  • serialNumber, model and manufacturer (or)

  • serialNumber and sku

    POST {base URL}/devices/search

    Request Body

    {
      "serialNumber": "1234567890",
      "model":"EC250",
      "manufacturer":"Trimble"
    }

    Response 200 OK

      [
      {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "trn": "trn:2:iam:us:account:75384d4c-f23d-447f-a44c-f8c8b35919f2",
          "serialNumber": "1234567890",
          "model": "EC250",
          "manufacturer": "Trimble",
          "sku": "1342AM2",
          "publicKey": "-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETLSvsnQYK8DKH5+zQqEwgp/ctpOy\\nnQg9Px0y6cyH8KZkb0RAGE75YCuAJl1HJzuiW2FtqRJtGY49BzKSN1S2rQ==\\n-----END PUBLIC KEY-----",
          "firmware": "firmware2.0",
          "description": "Device equipment",
          "metadata": {
          "createdBy": "users:00000000-0000-0000-0000-000000000000",
          "createdAt": "1970-01-01T00:00:00.000Z",
          "updatedBy": "users:00000000-0000-0000-0000-000000000000",
          "updatedAt": "1970-01-01T00:00:00.000Z"
          }
      }
      ]

  • Use the Transfer API to initiate transfer

    Immediate Transfer:

    POST {base URL}/devices/{deviceId}/transfer

    Request Body

    {
      "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1"
    }

    Response 201 Created

      {
        "accountId":"f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
        "deviceId":"3a10a36e-12ea-4c98-aa57-3e970bcea56c",
        "status":"APPROVED"
      }

    Scheduled Transfer:

    For implicit transfers, you can optionally schedule the transfer to occur at a specific date and time by providing the startDate field in the request. This allows dealers to schedule device transfers to customers in advance.

    POST {base URL}/devices/{deviceId}/transfer

    Request Body

    {
      "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
      "startDate": "2026-04-15T10:00:00Z"
    }

    Response 201 Created

      {
        "accountId":"f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
        "deviceId":"3a10a36e-12ea-4c98-aa57-3e970bcea56c",
        "status":"SCHEDULED",
        "startDate": "2026-04-15T10:00:00Z"
      }

    View Scheduled Transfers:

    Scheduled transfers can be viewed in two ways: list devices in SCHEDULED status, or use GET active transfer (GET Device Transfer API) for a specific device when an active transfer exists (PENDING or SCHEDULED).

    Both the dealer (source account) and customer (target account) can view devices with scheduled transfers using the List Devices API:

    GET {base URL}/devices?q=accounts.status==SCHEDULED

    Response 200 OK

    {
        "items": [
            {
                "metadata": {
                    "createdBy": "trn:2:iam:us:application:bc475617-rd16-4d32-a25c-f360b414d587",
                    "createdAt": "2026-04-10T15:36:52.708000Z",
                    "updatedBy": "trn:2:iam:us:application:bc475617-rd16-4d32-a25c-f360b414d587",
                    "updatedAt": "2026-04-10T15:36:52.708000Z"
                },
                "serialNumber": "12345",
                "manufacturer": "Trimble",
                "model": "Tablet",
                "sku": "1342AM2",
                "publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETLSvsnQYK8DKH5+zQqEwgp/ctpOy\nnQg9Px0y6cyH8KZkb0RAGE75YCuAJl1HJzuiW2FtqRJtGY49BzKSN1S2rQ==\n-----END PUBLIC KEY-----",
                "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
                "trn": "trn:2:iam:us:device:3a10a36e-12ea-4c98-aa57-3e970bcea56c"
            }
        ],
        "links": {...}
    }

    Note: Add &include=full to the request (GET {base URL}/devices?q=accounts.status==SCHEDULED&include=full) to get the full schema, including an accounts.self block with status: SCHEDULED and scheduledDate, plus the source-relation accounts.current. See the Account Details of Device section for an example payload.

    GET active transfer:

    GET {base URL}/devices/{deviceId}/transfer

    Response 200 OK

    {
        "sourceAccountId": "1c141f69-923b-4ef3-8c37-690c9b93a7e6",
        "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
        "status": "SCHEDULED",
        "startDate": "2026-04-15T10:00:00Z"
    }

    Failed Scheduled Transfers:

    If a scheduled transfer fails to execute at the specified time, the device status will be marked as FAILED. To view failed transfers:

    GET {base URL}/devices?q=accounts.status==FAILED

    When a transfer fails, you must re-initiate a new transfer request to complete the transfer operation.

  • The device ownership will be transferred to the target account immediately (if no startDate is provided) or at the scheduled date and time (if startDate is provided)

Tip

• Scheduled transfers can only be canceled by the source account (initiator) before the scheduled execution time.
• The target account cannot reject a scheduled transfer since it is an implicit transfer that does not require approval.

Dealer to Customer Implicit Transfer

A dealer can transfer a device to a customer with whom they have a business relationship. The device transfer request will be implicitly approved without requiring customer approval.

To enable this, first establish a doingBusinessWith relation between the dealer and customer accounts using the Dealer-Customer Account Relation API. Once this relation is established:

• When the dealer initiates a transfer to that customer, it will be automatically approved without requiring the customer’s approval
• When the customer initiates a transfer to return the device to the origin dealer, it will also be automatically approved without requiring the dealer’s approval
• Both dealers and customers can optionally schedule the transfer by providing a startDate in the request, allowing them to plan device transfers in advance

Note: For any other transfer use cases, the standard approval workflow must be followed.

Approval Workflow

• An authorized subject from source account can initiate the transfer request using the Transfer API.

  POST {base URL}/devices/{deviceId}/transfer

  Request Body

  {
      "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1"
  }

  Response 201 Created

  {
      "accountId":"f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
      "deviceId":"3a10a36e-12ea-4c98-aa57-3e970bcea56c",
      "status":"PENDING"
  }

• An authorized subject from target account can use the List Devices API to list down the transfer requests to their account

  GET {base URL}/devices?q=accounts.status==PENDING

  Response 200 OK

  {
      "items": [
          {
              "metadata": {
                  "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
                  "createdAt": "2025-04-23T18:58:50.008000Z",
                  "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
                  "updatedAt": "2025-04-23T18:58:50.008000Z"
              },
              "serialNumber": "12345",
              "manufacturer": "Trimble",
              "model": "Tablet",
              "sku": "1342AM2",
              "publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETLSvsnQYK8DKH5+zQqEwgp/ctpOy\nnQg9Px0y6cyH8KZkb0RAGE75YCuAJl1HJzuiW2FtqRJtGY49BzKSN1S2rQ==\n-----END PUBLIC KEY-----",
              "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
              "trn": "trn:2:iam:us:device:3a10a36e-12ea-4c98-aa57-3e970bcea56c"
          }
      ],
      "links": {...}
  }

  Note: Add &include=full to the request (GET {base URL}/devices?q=accounts.status==PENDING&include=full) to get the full schema, including an accounts.self block with status: PENDING and the source-relation accounts.current. See the Account Details of Device section for an example payload.

• The transfer request can be approved/reject using Transfer API by authorized subject from the target account. The action should be mentioned in the query param APPROVE or REJECT.

  PUT {base URL}/devices/{deviceId}/transfer?action=APPROVE

  Request Body

  {
      "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1"
  }

  Response 201 Created

  {
      "accountId":"f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
      "deviceId":"3a10a36e-12ea-4c98-aa57-3e970bcea56c",
      "status":"APPROVED"
  }

• The device is transferred to the target account. If reject action is given in input, the request will be rejected.

Note: If a Dealer and Customer have a doingBusinessWith relation, devices can be implicitly transferred (without requiring approval) in both directions between these accounts. See the Dealer to Customer Implicit Transfer section for details. All other transfer use cases follow the approval workflow described above.

Cancel a transfer request

A transfer request can be canceled by the initiator (source account) of the request using the Transfer API. This applies to both PENDING and SCHEDULED transfer requests.

PUT {base URL}/devices/{deviceId}/transfer?action=CANCEL

Request Body

{
    "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1"
}

Response 200 OK

{
    "accountId":"f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
    "deviceId":"3a10a36e-12ea-4c98-aa57-3e970bcea56c",
    "status":"CANCELED"
}

Tip

• Only the source account (initiator) can cancel transfer requests, including scheduled transfers.
• Scheduled transfers (status: SCHEDULED) can be canceled before the scheduled execution time.
• The target account cannot reject a scheduled transfer because it is an implicit transfer that does not require approval.

Check Active Transfer Status

You can check the active transfer status of a specific device using the GET Device Transfer API.

GET {base URL}/devices/{deviceId}/transfer

Response 200 OK

{
    "sourceAccountId": "1c141f69-923b-4ef3-8c37-690c9b93a7e6",
    "desiredAccountId": "f6ddd193-f555-4df3-a80d-a2ab622f5bb1",
    "status": "PENDING"
}

Note

The GET Device Transfer API only returns active transfer requests with status PENDING or SCHEDULED. If there is no active transfer for the device, you will receive a “No active transfer found for this device” error.

Device Account Transfer Status

Different Device Account Transfer workflows result in various device-account transfer status values, as illustrated in the diagram below.

Account Details of Device

Device account details can be retrieved from GET Device API / LIST Device API, by setting the query parameter include=full. This returns the accounts.self, accounts.current.name, and accounts.previous.name fields in the response.

The accounts.self object is caller-relative and always populated when include=full. Its meaning depends on the endpoint:

• GET /devices - caller account information.
• GET /devices/{deviceId} - currently committed account information for the device.
• GET /accounts/{accountId}/doingBusinessWith/{targetAccountId}/devices - customer account information.

When accounts.self.status is SCHEDULED, the response also includes accounts.self.scheduledDate.

GET Device

GET {base URL}/devices/{deviceId}?include=full

LIST Devices

GET {base URL}/devices?include=full

Response 200 OK

{
  "metadata": {
    "createdBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
    "createdAt": "2025-04-23T18:58:50.008000Z",
    "updatedBy": "trn:2:iam:us:user:bc475617-rd16-4d32-a25c-f360b414d587",
    "updatedAt": "2025-04-23T18:58:50.008000Z"
  },
  "serialNumber": "12345",
  "manufacturer": "Trimble",
  "model": "Tablet",
  "sku": "1342AM2",
  "accounts": {
    "self": {
      "id": "c9c5d208-94d9-48b2-8d91-f0ec34725093",
      "name": "Corporate DX",
      "status": "COMMITTED"
    },
    "current": {
      "id": "c9c5d208-94d9-48b2-8d91-f0ec34725093",
      "name": "Corporate DX"
    },
    "previous": {
      "id": "c0d32b11-6499-468f-88cd-4f0148fefb80",
      "name": "Civil Systems"
    }
  },
  "status": "BLOCKED",
  "statusMetaData": {
    "reason": "Stolen",
    "comment": "device is blocked"
  },
  "certRotationLock": false,
  "purchaseOrderNumber":"PO123456",
  "salesOrderNumber":"SO123456",
  "friendlyName": "Survey Rover - Site A",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETLSvsnQYK8DKH5+zQqEwgp/ctpOy\nnQg9Px0y6cyH8KZkb0RAGE75YCuAJl1HJzuiW2FtqRJtGY49BzKSN1S2rQ==\n-----END PUBLIC KEY-----",
  "id": "3a10a36e-12ea-4c98-aa57-3e970bcea56c",
  "trn": "trn:2:iam:us:device:3a10a36e-12ea-4c98-aa57-3e970bcea56c"
}

Note

• Filtering by accounts.status in the LIST Devices API supports:
  • Single value: COMMITTED, TRANSFERRED, PENDING, and SCHEDULED are permitted. REJECTED, CANCELED, and FAILED are restricted as filter values.
  • Multi-value: permitted only when the set includes COMMITTED (for example, (COMMITTED,SCHEDULED) or (COMMITTED,SCHEDULED,REJECTED)). Sets that do not contain COMMITTED - for example (TRANSFERRED,SCHEDULED) or (REJECTED,SCHEDULED) - are restricted.
• When include=full is specified with accounts.status==TRANSFERRED, the devices with TRANSFERRED accounts.status are returned only if it is an immediate transfer by the LIST Devices API.
• You can view pending transfers using q=accounts.status==PENDING and scheduled transfers using q=accounts.status==SCHEDULED.
• The accounts.self object (returned with include=full) is caller-relative and always populated. Its meaning depends on the endpoint:
  • GET /devices - caller account information.
  • GET /devices/{deviceId} - currently committed account information.
  • GET /accounts/{accountId}/doingBusinessWith/{targetAccountId}/devices - customer account information.