# Get units

Retrieve units with optional filtering and pagination

Endpoint: GET /units
Version: 1.1.1
Security: BearerAuth

## Query parameters:

  - `unitIds` (array)
    Filter by comma-separated list of unit IDs
    Example: [12345]

  - `extracted_from` (string)
    Any string that can be used to identify the unit in an external system. Essentially the same as an external_id, but not limited to an ID format. Uniqueness is not enforced.
    Example: "f78125c"

  - `accountId` (string)
    Filter by account ID
    Example: "4b88ff32-8ba0-4bbf-8e60-c789909ac176"

  - `statuses` (array)
    Filter by comma-separated list of unit statuses
    Enum: "Incomplete", "Under Review", "Available", "Archived", "Leased", "On Hold", "Expired", "Withdrawn", "Withdrawal Requested", "Price Analysis"

  - `limit` (integer)
    Maximum number of items to return per page (default 50, max 100)
    Example: 25

  - `page_number` (integer)
    Page number for pagination (0-indexed, default 0)
    Example: 1

## Response 200 fields (application/json):

  - `id` (integer, required)
    Unique identifier for the unit
    Example: 3318

  - `created_at` (string, required)
    Timestamp when the unit was created
    Example: "2024-10-05T18:53:03.406168Z"

  - `updated_at` (string, required)
    Timestamp when the unit was last updated
    Example: "2024-10-05T18:53:03.406168Z"

  - `address` (integer, required)
    ID of the address record associated with this unit
    Example: 957

  - `property_type` (string)
    Type of property
    Enum: "SINGLE FAMILY RESIDENCE", "DUPLEX", "TRIPLEX", "MULTI-FAMILY", "CONDO", "TOWNHOUSE", "ROOM", "ADU"

  - `bedrooms` (string)
    Number of bedrooms
    Example: "3"

  - `bathrooms` (string)
    Number of bathrooms
    Example: "2"

  - `sqft` (string)
    Square footage of the unit
    Example: "1378"

  - `furnished` (boolean)
    Whether the unit is furnished

  - `renovated` (string)
    Whether the unit has been renovated
    Example: "No"

  - `num_parking_spots` (string)
    Number of parking spots
    Example: "2"

  - `laundry` (string)
    Laundry options
    Enum: "In Unit", "Shared", "Coin-op", "Hookups but no machines", "Machines In Unit - Tenant Responsible", "None"

  - `target_rental_rate` (string)
    Target rental rate for the unit in dollars per month. 1925 means $1925/month
    Example: "1925"

  - `is_occupied` (boolean)
    Whether the unit is currently occupied

  - `earliest_move_in_date` (string)
    Earliest date the unit is available for move-in
    Example: "2024-10-12"

  - `allow_cooperating_brokers` (boolean,null)
    Whether cooperating brokers are allowed
    Example: true

  - `desired_lease_duration_months` (array)
    Desired lease duration in months
    Example: [12]

  - `pets_allowed` (string,null)
    Pet policy
    Enum: "Yes", "Yes with pet fee", "Dogs only", "Dogs only with pet fee", "Cats only", "Cats only with pet fee", "No"

  - `pet_restrictions` (string)
    Restrictions on pets
    Example: "A MINIMUM NON-REFUNDABLE pet fee in the amount of $300 per pet is required"

  - `hoa_app_required` (boolean,null)
    Whether HOA application is required
    Example: true

  - `hoa_app_fee` (number,null)
    HOA application fee in dollars
    Example: 100

  - `hoa_application_url` (string,null)
    URL for HOA application
    Example: "https://example.com/application"

  - `key_access` (string)
    Key access information
    Enum: "Digital Lockbox Connected to RentEngine", "Single code lockbox with key", "Digital door lock with code", "I will add this later", "Accompanied Showing"

  - `access_instructions` (string)
    Instructions for accessing the unit
    Example: "Lockbox/Door Code: Tenant Turner"

  - `min_resident_qualifications` (string)
    Minimum qualifications for residents

  - `utilities_included` (array)
    Utilities included in rent
    Enum: "Water", "Sewer/Septic", "Trash", "Wifi/Internet", "Cable/TV", "Electricity", "Gas", "HOA", "Lawn Care", "Pool Service", "Pest Control"

  - `parking_type` (array)
    Type of parking available
    Enum: "Street", "Carport", "Assigned Spots", "Driveway", "Shared Garage", "Private Garage", "Paid Parking"

  - `storm_protection` (string)
    Storm protection features
    Example: "None"

  - `status` (string)
    Current status of the unit
    Example: "Leased"

  - `send_showing_notifications` (boolean)
    Whether to send showing notifications
    Example: true

  - `send_leasing_update_email` (boolean)
    Whether to send leasing update emails
    Example: true

  - `extracted_from` (string)
    Source of the unit data. Can be a any string. Essentially the same as an external_id. Uniqueness is not enforced.
    Example: "f123abc"

  - `marketing_description` (string)
    Marketing description of the unit
    Example: "**AVAILABLE NOW** 3 Bedroom 2 Bathroom Townhome For Rent in Meadow Woods!"

  - `marketing_photos` (array)
    Photos of the unit

  - `marketing_photos.path` (string)
    Either the original image URL or the file path in the RentEngine storage. When updating, provide the external image url.

  - `marketing_photos.hidden` (boolean)

  - `marketing_photos.original` (string,null)
    The external image URL from where the image was imported to RentEngine. Not required as it will be set/overwritten by RentEngine when setting the path field.
    Example: "https://images.cdn.appfolio.com/allegiant/images/8eb1431e-d325-4a43-9fbc-cea487e609f1/large.jpeg"

  - `commission_amount` (string)
    Commission amount
    Example: "1"

  - `commission_type` (string)
    Type of commission
    Enum: "percent", "fixed", "none", "contact_mls_agent"

  - `imported_by` (string,null)
    Who/what imported the unit
    Example: "Rentvine Sync"

  - `floor_number` (integer)
    Floor number of the unit. Best to use the floor of the entrance door if the unit spans multiple floors.
    Example: 1

  - `has_elevator` (boolean,null)
    Whether the building has an elevator

  - `hoa_details` (object)
    Details about the HOA

  - `hoa_details.isInHOA` (boolean)
    Example: true

  - `hoa_details.hoaAmenities` (array)
    Example: ["Clubhouse","Pool"]

  - `account_id` (string)
    ID of the account that owns the unit. Must be a valid account for which the api key has access.
    Example: "269bf205-d876-42f5-988d-6f40891df58a"

  - `owner_emails` (array)
    Email addresses of the owners
    Example: ["rick@amgrents.com"]

  - `accepts_vouchers` (boolean,null)
    Whether the unit accepts housing vouchers.
    Example: true

  - `internal_notes` (string,null)
    Internal notes about the unit.
    Example: "Garage work scheduled for Monday."

  - `amenities` (array)
    All amenities of the unit
    Example: ["Dishwasher","Stove","Range Oven","Refrigerator"]

  - `monthly_fees` (array,null)
    Monthly recurring fees

  - `monthly_fees.name` (string)
    Example: "Resident Benefit Package"

  - `monthly_fees.amount` (number)
    Depending on the type field, this can represet either $55.50 of 55.5% of 1 month's rent.
    Example: 55.5

  - `monthly_fees.type` (string)
    Determines if  amount is calculated as an absolute dollar value or as a percent of 1 month's rent.
    Enum: "percent", "dollar"

  - `move_in_fees` (array,null)
    Fees required at move-in

  - `multifamily_property_id` (string,null)
    ID of the multifamily property
    Example: "421e4567-e89b-12d3-a456-426614174000"

  - `showing_method` (string,null, required)
    Method for showing the unit
    Enum: "Accompanied", "Remote Guided", "Remote Guided with Gated Access", "Self Guided"

  - `floorplans_id` (string,null)
    ID of the floorplan
    Example: "451e4567-e89b-12d3-a456-426614174000"

  - `video_url` (string,null)
    URL of video tour (such as YouTube, Vimeo, Zillow Tour, Matterport, Ricoh360, or zInspector tour)
    Example: "https://www.youtube.com/watch?v=1234567890"

  - `subteam_id` (string,null)
    ID of the subteam managing the unit
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `prescreen_template_id` (string,null)
    ID of the prescreening template to use for this unit, if it is null the default template will be used.
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `structured_access_instructions` (object)
    Structured access instructions that vary based on showing_method:
- For "Self Guided" showing method: Use the self-guided showing instructions object
- For "Remote Guided" or "Remote Guided with Gated Access" showing methods: Use the self-guided showing instructions object
- For "Accompanied" showing method: Use either the legacy accompanied or accompanied showing instructions object

When updating structured_access_instructions, the showing_method field must also be set.

  - `enable_send_report` (boolean, required)
    Whether to enable sending reports
    Example: true

  - `earliest_showing_date` (string)
    Earliest date the unit can be shown
    Example: "2024-10-12"

  - `security_deposit_amount` (number,null)
    Amount of security deposit in dollars. 1000 means $1000.21
    Example: 1000.21

  - `require_last_month_rent` (boolean,null)
    Whether last month's rent is required upfront
    Example: true

  - `requires_voucher` (boolean,null)
    Whether a voucher is required

  - `custom_application_url` (string)
    URL for custom application
    Example: "https://app.findigs.com/apply/unitid=70f51c4c-d708-402e-9a5f-bb6fd60b6cf2"

  - `include_feedback_leasing_report` (boolean)
    Whether to include feedback in leasing reports
    Example: true

  - `year_built` (number,null)
    Year the property was built
    Example: 2020

  - `application_fee` (number,null)
    Application fee amount in dollars
    Example: 50

## Response 400 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (array)
    Detailed error information
    Example: [{"keyword":"required","dataPath":"","schemaPath":"#/required","params":{"missingProperty":"account_id"},"message":"should have required property 'account_id'"}]

## Response 401 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (array)
    Detailed error information
    Example: [{"keyword":"required","dataPath":"","schemaPath":"#/required","params":{"missingProperty":"account_id"},"message":"should have required property 'account_id'"}]

## Response 500 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (array)
    Detailed error information
    Example: [{"keyword":"required","dataPath":"","schemaPath":"#/required","params":{"missingProperty":"account_id"},"message":"should have required property 'account_id'"}]