# Device Idle Image

By default, Finix terminals display a standard welcome screen when idle. You can replace the default idle screen image with your own logo or image using the Finix Dashboard or API.

## Using the Finix Dashboard

You can replace the default idle screen image on the Finix Dashboard.

1. From the **Device Management** screen, click the device you want to update from the device list.


Device management list page
1. From the device details screen, click **Edit** in the **Idle Screen** section.


Device details page - edit idle screen
1. In the **Update Idle Screen** modal, upload your idle screen image. Optionally provide an idle message to display along with the idle screen image.


Device details page - update idle screen modal
The next time the device goes idle, your idle screen image displays instead of the default idle screen.

To reset the idle screen to the default, click **Reset** from the **Update Idle Screen** modal.

## Using the API

To replace the default idle screen image using the API, you must:

1. Create a File resource.
2. Upload the idle image to the File resource.
3. Verify the image file is approved.
4. Update the Device resource to use the idle image.


Image file vs. the File resource
Your image file is not the same as a File resource. [Create a File resource](#1-create-a-file-resource) first to obtain an ID, then use that ID to upload your image file to it.

### 1. Create a File resource

Send a POST /files request to create a File resource.

In the request, include the following fields:

- `linked_to` - The Merchant `id`.
- `type` - Set to `DEVICE_IDLE_IMAGE`.
- `display_name` - A human-readable name for the File.



```shell Create a File resource for device idle image
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/files \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "display_name": "Custom device idle image",
    "linked_to": "MUvWVhLpLj9w7kV1EXA7yvzc",
    "type": "DEVICE_IDLE_IMAGE"
  }'
```

A successful request returns a `201 Created` status with the response body containing the newly created File resource. The `REQUIRES_UPLOAD` status indicates that the image upload step is still pending.

Save the resource `id` for the next step.


```json
{
  "id" : "FILE_eUN3CgqaEiYS84QhrDy42T",
  "status" : "REQUIRES_UPLOAD",
  "created_at" : "2026-09-16T22:58:39.586982Z",
  "updated_at" : "2026-09-16T22:58:39.586982Z",
  "linked_type" : "MERCHANT",
  "linked_to" : "MUvWVhLpLj9w7kV1EXA7yvzc",
  "extension" : null,
  "display_name" : "Custom device idle image",
  "type" : "DEVICE_IDLE_IMAGE",
  "platform_id" : "PLoMxXWbqwEMT5N1upSaNUbJ",
  "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "tags" : { },
  "identity_id" : "IDnT3ff71VShf6dB2ShcPozq",
  "entity_id" : null,
  "entity_type" : null,
  "size_in_bytes" : null,
  "file_name" : null
}
```

### 2. Upload the device idle image

Send a POST /files/{file_id}/upload request as `multipart/form-data`, using the File resource `id` from the previous step.


```shell
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/files/FILE_eUN3CgqaEiYS84QhrDy42T/upload \
  -H 'Content-Type: multipart/form-data' \
  -H 'Finix-Version: 2022-02-01' \
  -F file=@/Users/Desktop/device-idle-image.png
```

### 3. Verify the image is approved

Wait until the File resource reports `status: UPLOADED` before assigning it to a device. You can confirm the status in one of two ways:

- **Poll for status:** Send a GET /files/{file_id} request and check the `status` field in the response.
- **Subscribe to webhooks:** Register a [webhook](/additional-resources/developers/webhooks/webhook-events#file-approved) to receive a notification when the File's status changes.


### 4. Update device idle image

Now that the image is approved, update the Device resource by sending a PUT /devices/{device_id} request with your custom idle image.

You can also customize the text shown on the idle screen using the `idle_message` field.

Example
API Definition
A successful request returns a `200 OK` status with the response body containing the Device with the updated idle image and idle message.

The next time the device goes idle, your idle screen image displays instead of the default idle screen.

To reset the idle screen to the default, send a PUT /devices/{device_id} request with `configuration.idle_image_file_id` set to `null`.