> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.travtus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create/Update Leases And Tenants

> This endpoint creates or updates a lease and tenant records for it.

You must specify either a `unit_id` or `unit_external_ref` for your lease.

If the corresponding unit record does not exist, you must create it separately via the relevant unit/property endpoints.

### Header

<ParamField header="Authorization" type="string" default="none" required>
  The authentication token for your request
</ParamField>

### Body

<ParamField body="lease" type="object" default="none" required>
  The parameters for the lease to update or create.

  <Expandable title="lease">
    <ParamField body="identifier" type="string" default="none">
      A unique identifier for the lease.

      This will be used when determining whether a lease needs to be updated or created.

      If this matches a lease that lease will be updated, otherwise a new one will be created.

      The identifier for a lease can not be updated once it has been set.

      When creating a new lease, a random, unique identifier will be set.

      Any value passed in this request will only be used for finding an existing lease.
    </ParamField>

    <ParamField body="start_date" type="string" default="none">
      The start date of the lease.
    </ParamField>

    <ParamField body="end_date" type="string" default="none">
      The end date of the lease.
    </ParamField>

    <ParamField body="move_in_date" type="string" default="none">
      The move in date of the lease.
    </ParamField>

    <ParamField body="unit_id" type="string" default="none">
      The id of the property associated with the lease.
    </ParamField>

    <ParamField body="unit_external_ref" type="string" default="none">
      The id of the property associated with the lease.
    </ParamField>

    <ParamField body="is_furnished" type="boolean" default="none">
      Whether the lease is for a furnished or unfurnished property.
    </ParamField>

    <ParamField body="minimum_days_notice" type="integer" default="none">
      Minimum days of notice that must be given to break the lease agreement.
    </ParamField>

    <ParamField body="deposit" type="float" default="none">
      The deposit amount for the lease.
    </ParamField>

    <ParamField body="rent" type="float" default="none">
      The rent amount for the lease.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tenants" type="[object]" default="none">
  A list of tenants to be associated with the created or updated lease.

  <Expandable title="tenant">
    <ParamField body="email_address" type="string" default="none">
      The email adddress of the tenant.
    </ParamField>

    <ParamField body="first_name" type="string" default="none">
      The first name of the tenant.
    </ParamField>

    <ParamField body="last_name" type="string" default="none">
      The last name of the tenant.
    </ParamField>

    <ParamField body="external_ref" type="string" default="none">
      The external reference of the tenant.

      This is typically an identifier you may use for person records in your own system.
    </ParamField>

    <ParamField body="phone_number" type="string" default="none">
      The phone number of the tenant.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ParamField name="success" type="boolean">
  Whether the API operation was successful or not.
</ParamField>

<ParamField name="lease" type="string">
  The identifier for the modified or created lease.
</ParamField>

### Errors

Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.

Status Code - 400

```json Missing Authorization header theme={null}
{
   "error": {
    "type": "missing_authorization",
    "message": "Your request does not include an 'Authorization' header with a bearer token for your account."
  }
}
```

Status Code - 401

```json Expired Authorization header bearer token value theme={null}
{
   "error": {
    "type": "expired_token",
    "message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
  }
}
```

Status Code - 401

```json Invalid Authorization header bearer token value theme={null}
{
   "error": {
    "type": "invalid_authorization",
    "message": "The bearer token you have provided in the 'Authorization' header is invalid."
  }
}
```

Status Code - 400

Returned if neither a unit id or a unit external reference is passed in the request body

```json No unit specified for the lease theme={null}
{
   "error": {
    "type": "no_unit",
    "message": "No unit id or unit external reference provided."
  }
}
```

Status Code - 400

Returned if a unit with the specified unit id or unit external reference could not be retrieved

```json Unit to use for lease not found theme={null}
{
   "error": {
    "type": "unit_not_found",
    "message": "No unit with the provided unit id or unit external reference."
  }
}
```

<RequestExample>
  ```bash Example Request theme={null}
  curl --location --request POST 'https://api.travtus.com/leases/create/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>' \
  --data-raw '{
    "lease": {
      "identifier": "lease-1",
      "start_date": "2023-01-17",
      "end_date": "2023-12-17",
      "move_in_date": "2023-01-17",
      "unit_id": "unit-id-1",
      "unit_external_ref": "unit-external-ref-1",
      "is_furnished": false,
      "minimum_days_notice": 30,
      "deposit": 1400.0,
      "rent": 700.0
    },
    "tenants": [
      {
        "email_address": "test.tenant.1@travtus.com",
        "first_name": "Test",
        "last_name": "Tenant 1",
        "external_ref": "id-1",
        "phone_number": "01234567890"
      },
      {
        "email_address": "test.tenant.2@travtus.com",
        "first_name": "Test",
        "last_name": "Tenant 2",
        "external_ref": "id-2",
        "phone_number": "01234567891"
      }
    ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "lease": "lease-1"
  }
  ```
</ResponseExample>