# Create or update a unit

Create a new unit or update an existing one.

## Insert vs Update
- : When no  is provided, a new unit will be created. Required fields for creation include , , , and .
- : When an  is provided, an existing unit will be updated. No other fields are required.

## Address Updates
When updating a unit, if you include the  field, you must provide all address components (, , , , ). Partial address updates are not supported.

## Structured Access Instructions
When providing , the  field must also be set. The structure of the access instructions depends on the showing method:
- For "Self Guided", "Remote Guided", or "Remote Guided with Gated Access" methods: Include fields like , , etc.
- For "Accompanied" method: Include fields like , , etc.


Endpoint: POST /units
Version: 1.1.1
Security: BearerAuth

## Request fields (application/json):

  - `id` (number)
    Unit ID. If provided, the unit will be updated; if not, a new unit will be created.
    Example: 3318

  - `address` (object)
    Unit address. All fields must be provided together when updating.

  - `address.street_number` (string, required)
    Street number
    Example: "123"

  - `address.street_name` (string, required)
    Street name
    Example: "Main St"

  - `address.unit` (string)
    Unit/apartment number
    Example: "4B"

  - `address.zip_code` (string, required)
    ZIP code
    Example: "12345"

  - `address.state` (string, required)
    State (two-letter code)
    Example: "CA"

  - `address.country` (string)
    Country
    Enum: "United States"

  - `address.city` (string, required)
    City
    Example: "San Francisco"

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

  - `bedrooms` (number)
    Number of bedrooms
    Example: 3

  - `bathrooms` (number)
    Number of bathrooms
    Example: 2

  - `sqft` (number)
    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` (number)
    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` (number)
    Target rental rate in dollars per 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)
    Whether cooperating brokers are allowed
    Example: true

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

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

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

  - `hoa_details` (object)

  - `hoa_details.isInHOA` (boolean)
    Whether the unit is in an HOA
    Example: true

  - `hoa_details.hoaAppRequired` (boolean)
    Whether HOA application is required
    Example: true

  - `hoa_details.hoaAppFee` (number)
    HOA application fee in dollars
    Example: 100

  - `hoa_details.hoaApplicationUrl` (string)
    URL for HOA application
    Example: "https://example.com/application"

  - `hoa_details.hoaApprovalTimeframe` (string)
    Timeframe for HOA approval
    Example: "2 weeks"

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

  - `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"

  - `structured_access_instructions` (object)
    Structured access instructions that vary based on showing_method.
When providing structured_access_instructions, showing_method must also be set.

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

  - `additional_info` (string)
    Additional information about the unit
    Example: "Newly renovated kitchen"

  - `min_resident_qualifications` (string)
    Minimum qualifications for residents
    Example: "Credit score 650+, income 3x rent"

  - `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", "Parking Lot"

  - `status` (string)
    Current status of the unit
    Enum: "Incomplete", "Available", "On Hold", "Leased", "Archived", "Withdrawn", "Withdrawal Requested"

  - `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!"

  - `marketing_photos` (array)

  - `marketing_photos.path` (string, required)
    Either the original image URL or the file path in the RentEngine storage
    Example: "https://example.com/images/unit123.jpg"

  - `marketing_photos.hidden` (boolean, required)
    Whether the photo is hidden

  - `marketing_photos.original` (string)
    The external image URL from where the image was imported
    Example: "https://example.com/images/unit123_original.jpg"

  - `commission_amount` (number)
    Commission amount
    Example: 1

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

  - `imported_by` (string)
    Who/what imported the unit
    Example: "API Import"

  - `floor_number` (number)
    Floor number of the unit
    Example: 1

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

  - `account_id` (string)
    ID of the account that owns the unit
    Example: "269bf205-d876-42f5-988d-6f40891df58a"

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

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

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

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

  - `move_in_fees` (array)

  - `move_in_fees.type` (string, required)
    Type of fee calculation
    Enum: "percent", "dollar"

  - `move_in_fees.amount` (number, required)
    Fee amount
    Example: 150

  - `move_in_fees.name` (string, required)
    Name of the fee
    Example: "Admin Fee"

  - `monthly_fees` (array)

  - `multifamily_property_id` (string,null)
    ID of the multifamily property. Pass string 'null' to clear this field.
    Example: "421e4567-e89b-12d3-a456-426614174000"

  - `floorplans_id` (string,null)
    ID of the floorplan. Pass string 'null' to clear this field.
    Example: "451e4567-e89b-12d3-a456-426614174000"

  - `video_url` (string)
    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. Pass string 'null' to clear this field.
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `prescreen_template_id` (string)
    ID of the prescreening template to use for this unit
    Example: "123e4567-e89b-12d3-a456-426614174000"

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

  - `security_deposit_amount` (number)
    Amount of security deposit in dollars
    Example: 1000

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

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

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

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

  - `after_upsert_action` (object)
    Actions to perform after updating the unit

  - `after_upsert_action.action` (string, required)
    The action to perform after updating the unit
    Enum: "cancel_scheduled_bookings", "notify_all_prospects"

  - `after_upsert_action.should_cancel_scheduled_bookings` (boolean)
    Whether to cancel any scheduled/confirmed bookings when updating the unit (only applies to cancel_scheduled_bookings action)
    Example: true

  - `after_upsert_action.custom_sms_message` (string)
    Custom SMS message to send to prospects (applies to all actions)
    Example: "Hi, the unit is available for showing. Please contact us at (555) 123-4567 with any questions."

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

## Response 200 fields (application/json):

  - `unit` (object)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `unit.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"

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

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

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

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

  - `unit.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"

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

  - `unit.min_resident_qualifications` (string)
    Minimum qualifications for residents

  - `unit.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"

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

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

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

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

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

  - `unit.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"

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

  - `unit.marketing_photos` (array)
    Photos of the unit

  - `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.

  - `unit.marketing_photos.hidden` (boolean)

  - `unit.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"

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

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

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

  - `unit.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

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

  - `unit.hoa_details` (object)
    Details about the HOA

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

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

  - `unit.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"

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

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

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

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

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

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

  - `unit.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

  - `unit.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"

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

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

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

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

  - `unit.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"

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

  - `unit.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"

  - `unit.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.

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

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

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

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

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

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

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

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

  - `unit.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'"}]