Device REST API: registration and inventory
The five v5 operations for listing, enrolling, inspecting, updating, and removing merchant cloud devices.
Environment and authentication
Base URL for every operation on this page: https://sandbox.nmi.com/api/v5. Send the private key directly as the Authorization header value, without a Bearer prefix. JSON requests use Content-Type: application/json. Keep credentials on your backend and select the merchant and device through your own authorized session. These paths are v5; do not substitute v2 camelCase fields or Classic security_key request bodies. Authorization: YOUR_SANDBOX_PRIVATE_KEY Content-Type: application/json Examples here describe sandbox request shapes only. They do not create a device, prompt a customer, or move money.
List devices — GET /devices
Returns merchant cloud devices. HTTP 200 is success; 401 indicates authentication failure. The three boolean-like query parameters below are strings, not JSON booleans. Parameter Type / requirement Meaning or constraint limit integer; optional 1–100; default 50. offset integer; optional At least 0; default 0. include_status string true or false Default false; adds battery and Wi-Fi information. include_connection_info string true or false Default true; adds connection information. connection_status string true or false Connected-only or disconnected-only filter; omit for both. GET /api/v5/devices?limit=50&offset=0&include_status=true HTTP/1.1 Host: sandbox.nmi.com Authorization: YOUR_SANDBOX_PRIVATE_KEY
Register — POST /devices
Enroll with the registration code presented for the device. HTTP 201 confirms registration; 400 is invalid input and 401 is unauthorized. Parameter Type / requirement Meaning or constraint registration_code string; required Device registration code. nickname string; optional Human-readable device label. default boolean; optional Set the merchant default cloud device. { "registration_code": "YOUR_DEVICE_CODE", "nickname": "Front counter", "default": false }
Read one device — GET /devices/{device_id}
device_id is a required string path parameter. Optional include_status accepts the query strings true or false and defaults to false. HTTP 200 returns the device; 401 is unauthorized and 404 means it was not found.
Update — PATCH /devices/{device_id}
device_id is required. The JSON body supports optional nickname (string) and default (boolean). HTTP 200 indicates success; 401 and 404 cover authentication and missing device. Recommended application behavior: submit only the fields being changed. { "nickname": "Service desk" }
Deregister — DELETE /devices/{device_id}
device_id is the required string path parameter. HTTP 204 reports successful removal, with no response body to parse. HTTP 401 is unauthorized; 404 means device not found. A deregistered device can no longer process transactions. Recommended application sequencing: remove the device from new-order routing and reconcile active work before deregistration. Deregistration is not transaction cancellation.
Response scope and inventory state
DeviceResponse requires object="device", id and registration_status (registered or deregistered). The response label is device_nickname, while registration and update requests use nickname. make, model, serial_number, connection_status, dates, battery_info and wifi_info may be nullable. DeviceListResponse contains devices, total_count, limit, offset and has_more. Use has_more with pagination rather than assuming one page is the complete merchant estate. The schema descriptions mention current_status for diagnostic objects, while the actual documented query parameter is include_status; use the declared query parameter. Asynchronous device payments Device prompts and displays
Detailed local operation contracts
Expand the corresponding local contract for full request and response structures, including nested fields. These contracts preserve the v5 operation boundary. list devices v5 register device v5 get device v5 update device v5 deregister device v5