# List Devices

Retrieve a list of Devices. 

For details on how to query endpoints using the available parameters, see Query Parameters.

Endpoint: GET /devices
Version: 2022-02-01
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

## Query parameters:

  - `after_cursor` (string)
    Return every resource created after the cursor value.

  - `application_id` (string)
    Filter by Application ID.
    Example: "APc9vhYcPsRuTSpKD9KpMtPe"

  - `before_cursor` (string)
    Return every resource created before the cursor value.

  - `created_at.gte` (string)
    Filter where created_at is after the given date.
    Example: "2022-09-27T11:21:23"

  - `created_at.lte` (string)
    Filter where created_at is before the given date.
    Example: "2026-09-27T11:21:23"

  - `description` (string)
    Filter by the description.

  - `enabled` (boolean)
    Filter by the enabled value.
    Example: true

  - `limit` (integer)
    The numbers of items to return.
    Example: 10

  - `merchant_id` (string)
    Filter by Merchant ID.
    Example: "MUeDVrf2ahuKc9Eg5TeZugvs"

  - `name` (string)
    Filter by the name.
    Example: "john%%20smith"

  - `model` (string)
    Filter by the model.
    Example: "PAX_A800"

  - `tags.key` (string)
    Filter by the tag's key. For more information, see Tags.
    Example: "card_type"

  - `tags.value` (string)
    Filter by the tag's value. For more information, see Tags.
    Example: "business_card"

  - `serial_number` (string)
    Filter by the serial number.
    Example: "2210074802"

  - `updated_at.gte` (string)
    Filter where updated_at is after the given date.
    Example: "2022-09-27T11:21:23"

  - `updated_at.lte` (string)
    Filter where updated_at is before the given date.
    Example: "2026-09-27T11:21:23"

## Response 200 fields (application/json):

  - `page` (object)
    Details the page that's returned.

  - `page.limit` (integer)
    The number of entries to return.

  - `page.next_cursor` (string,null)
    The cursor to use for the next page of results.

  - `_embedded` (object)

  - `_embedded.devices` (array)

  - `_embedded.devices.id` (string)
    The ID of the resource.

  - `_embedded.devices.created_at` (string)
    Timestamp of when the object was created.

  - `_embedded.devices.updated_at` (string)
    Timestamp of when the object was last updated.

  - `_embedded.devices.android_version` (string)
    The Android version installed on the Device.

  - `_embedded.devices.configuration` (object)
    Information used to configure how the Device handles transaction flows.

  - `_embedded.devices.configuration.allow_debit` (boolean)
    Enable processing of transactions through Debit rails. If set to false, Debit card transactions will instead be processed through Credit rails.

  - `_embedded.devices.configuration.allow_standalone_authorizations` (boolean)
    Sets whether the device allows initialization authorizations on its interface.FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.allow_standalone_refunds` (boolean)
    Sets whether the device allows initialization refunds on its interface. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.allow_standalone_sales` (boolean)
    Sets whether the device allows initialization sales on its interface.

  - `_embedded.devices.configuration.bypass_device_on_capture` (boolean,null)
    Sets whether or not the device will be used to capture transactions. This field should be set to true unless there are special circumstances.

  - `_embedded.devices.configuration.check_for_duplicate_transactions` (boolean)
    Sets if the device will check for duplicate transactions. DATACAP_V1 only.

  - `_embedded.devices.configuration.display_tip_on_receipt` (boolean)
    Sets whether the device will display the blank tip amount on the receipt for authorizations to be later captured. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.idle_image_file_id` (string,null)
    The ID of the file to be displayed on the device when it is idle. Passing a value of null resets the device's idle image to the default.

  - `_embedded.devices.configuration.idle_message` (string,null)
    Sets the idle message text on the terminal. This is what will be presented on the welcome screen. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.prompt_amount_confirmation` (boolean)
    Sets if the cardholder needs to confirm the amount they'll pay. DATACAP_V1 only.

  - `_embedded.devices.configuration.prompt_for_signature` (string)
    Determines when the terminal prompts for an e-signature.

- ALWAYS: The terminal will always request an e-signature.  
- NEVER: The terminal will never request an e-signature.  
- ON_NETWORK_RECOMMENDATION: The terminal follows card network recommendations on whether to prompt for a signature.  
- ON_THRESHOLD_AMOUNT: The terminal requests an e-signature only when the transaction amount is greater than or equal to signature_threshold_amount.
    Enum: "ALWAYS", "NEVER", "ON_NETWORK_RECOMMENDATION", "ON_THRESHOLD_AMOUNT"

  - `_embedded.devices.configuration.prompt_manual_entry` (boolean)
    Sets if the device allows for manual entry as a card input method. DATACAP_V1 and FINIX_V1 only. On DATACAP_V1 if this is set to true manual entry will be the default entry option.

  - `_embedded.devices.configuration.prompt_receipt_confirmation` (boolean)
    Sets whether or not the device presents a screen prompting the buyer to print receipt at the end of the transaction flow. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.prompt_tip_on_screen` (boolean)
    Sets whether the device will display the suggested tipping screen. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.signature_threshold_amount` (any)
    The transaction amount at which the terminal prompts for an e-signature.

  - `_embedded.devices.configuration.surcharge_basis_points` (integer)
    Represents the transaction amount that a Merchant charges the buyer when creating a Transfer or an Authorization. The value cannot exceed 300 (i.e., 3%). For devices on Standalone Mode, the Finix Payment Application on the terminal will calculate and send a Transfer or an Authorization request with the surcharge added. Customers integrated directly into Finix API must contact Support to incorporate surcharging appropriately into their integration.

  - `_embedded.devices.configuration.tipping_details` (object)
    An object that sets the configurations for the tipping page if it appears. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.tipping_details.allow_custom_tip` (boolean)
    Allows the buyer to set a custom tip. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.tipping_details.fixed_options` (array)
    Sets the fixed amount that will be displayed on the terminal. Defaults to [100, 150, 200]. Must be three integer values that represent cent values. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.tipping_details.percent_options` (array)
    Sets the percentages that will be displayed on the terminal. Defaults to [18, 20, 22]. Must be three integer values that represent percentages. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.configuration.tipping_details.percent_tipping_threshold` (integer)
    The inclusive value at which the terminal will present a percent based prompt instead of a fixed value prompt. Defaults to false. FINIX_V1 and DUMMY_V1 only.

  - `_embedded.devices.description` (string,null)
    Additional information about device (e.g. self serving terminal).

  - `_embedded.devices.enabled` (boolean)
    Whether the Device is enabled. false indicates disabled.

  - `_embedded.devices.firmware_version` (string)
    The current version of the device's firmware.

  - `_embedded.devices.merchant` (string)
    ID of the Merchant resource.
    Example: "MUxxxxxxxxxxxxxxxxxx"

  - `_embedded.devices.model` (string)
    The model type of the Device.
    Enum: "PAX_A800", "PAX_A920PRO", "D135"

  - `_embedded.devices.name` (string)
    The display name of the Device used for filtering purposes.

  - `_embedded.devices.payment_app_version` (string)
    The device’s current app version.

  - `_embedded.devices.prompt_signature` (string)
    When to prompt for a signature.
    Enum: "ALWAYS"

  - `_embedded.devices.serial_number` (string,null)
    The serial_number is a unique identifier for the Device, located on the back and typically composed of ~16 digits. Ensure the serial number is set before activating the Device, though it can also be added later using a PUT request.

  - `_embedded.devices.tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `_embedded.devices._links` (object)
    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

  - `_embedded.devices._links.authorizations` (object)

  - `_embedded.devices._links.authorizations.href` (string)

  - `_embedded.devices._links.merchant` (object)
    Link to the Merhcant resource that was used in the request.

  - `_embedded.devices._links.self` (object)
    Link to the resource that was used in the request.

  - `_embedded.devices._links.transfers` (object)

  - `_links` (object)

  - `_links.next` (object)
    Link to the next page of entries.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.