Leasey.AI API Documentation

What changed in v2.0

Version 2.0 is a full REST redesign. If you integrated with v1, update your requests according to the tables below.

Reports API

Properties API

1. Getting Started

To use the Leasey External API you need three credentials:

curl -X GET "https://<base-url>/reports/showings?company_id=123" \
  -H "Authorization: Bearer <your-api-token>" \
  -H "X-Company-Password: <your-company-password>"

2. Authentication

Every request requires two levels of authentication.

Level 1 — API Token

Authorization: Bearer <api_token>

Level 2 — Company Credentials

Authentication errors

3. Environments & Base URL

Production:  https://uvciw58bnh.execute-api.ca-central-1.amazonaws.com/production
Staging:     https://hs52apwqwh.execute-api.ca-central-1.amazonaws.com/staging

4. Reports API

Headers

Query Parameters

curl -X GET "{base_url}/reports/showings?company_id=123&start_date=2024-11-01T00:00:00&end_date=2024-11-30T23:59:59" \
  -H "Authorization: Bearer <api_token>" \
  -H "X-Company-Password: <company_password>"

Response Fields

Query Parameters

curl -X GET "{base_url}/reports/leads?company_id=123&start_date=2024-01-01T00:00:00" \
  -H "Authorization: Bearer <api_token>" \
  -H "X-Company-Password: <company_password>"

Response Fields

Query Parameters

curl -X GET "{base_url}/reports/properties?company_id=123" \
  -H "Authorization: Bearer <api_token>" \
  -H "X-Company-Password: <company_password>"

Response Fields

5. Properties API

Required Body Fields

{
  "company_id": 123,
  "password": "<company_password>",
  "property": {
    "name": "Unit 2B",
    "address": "456 Oak Ave",
    "city": "Toronto",
    "province_state": "ON",
    "country": "Canada",
    "postal_code": "M5V 2T6",
    "unit_type": "apartment",
    "rental_space": "entire place",
    "rent_amount": "2100",
    "rent_payment_frequency": "monthly",
    "renewal_frequency": "month to month",
    "bedrooms": 2,
    "bathrooms": 1,
    "size_sqft": 850,
    "furnishing": 2,
    "parking_stalls": 1,
    "date_available": "2025-02-01",
    "building_name": "Oak Ave Apartments",
    "features": [
      { "id": 1, "value": 1 },
      { "id": 13, "value": 1 }
    ],
    "building_amenities": [
      { "id": 4, "value": 1 }
    ],
    "restrictions": [1, 2],
    "marketplaces": [
      { "name": "zillow", "enabled": true }
    ]
  }
}

Response 201 Created

{
  "success": true,
  "message": "Property created successfully.",
  "property_id": "a3f7b2d1-e894-4c1a-b5f0-1234567890ab",
  "url_slug": "unit-2b",
  "building_id": 55,
  "floorplan_id": 12,
  "building_amenities": {
    "building_id": 55,
    "inserted": 1,
    "skipped": []
  },
  "team_members": {
    "assigned": [45, 101],
    "created": [
      {
        "team_member_id": 101,
        "user_id": 305,
        "person_id": 488,
        "email": "sara.white@mycompany.com",
        "already_existed": false
      }
    ],
    "skipped": []
  }
}

Response Fields

{
  "company_id": 123,
  "password": "<company_password>",
  "property": {
    "rent_amount": "2200",
    "date_available": "2025-03-01"
  }
}

Query Parameters

6. Property Object Reference

All fields accepted in the property object for create and update requests.

Core Fields

Pricing & Lease Fields

Physical Fields

Features (Unit Amenities)

The features array controls unit-level amenity and utility availability. Each entry has an id and a value: 1 = Included in rent · 2 = Available, not included · 3 = Not available. Only include features you want to set — unspecified features default to not available.

"features": [
  { "id": 1,  "value": 1 },
  { "id": 13, "value": 1 },
  { "id": 20, "value": 2 }
]

Unit feature IDs — complete list

Building Fields

Building Amenities

The building_amenities array controls building-level amenities shared across all units. Each entry has an id and a value: 1 = Active/included · 2 = Available, not included · 3 = Not available. Providing this field replaces all existing building amenities. Requires building_id, building_name, or number_of_units to be set.

"building_amenities": [
  { "id": 4, "value": 1 },
  { "id": 11, "value": 1 }
]

Building amenity IDs — complete list

Owner Contact

Override the contact information shown on the listing.

Team Members

Assign team members to the property. Three styles can be mixed in the same array:

"team_members": [
  { "team_member_id": 45 },
  { "email": "agent@mycompany.com" },
  {
    "email": "sara.white@mycompany.com",
    "first_name": "Sara",
    "last_name": "White",
    "role_id": 12,
    "is_admin": false,
    "timezone": "America/Vancouver"
  }
]

Restrictions

Providing this field replaces all existing restrictions.

Photos

Providing this field replaces all existing photos. Photos are displayed in the order provided; the first photo is used as the main listing image. URLs must start with https://.

"photos": [
  { "url": "https://cdn.example.com/unit2b-main.jpg" },
  { "url": "https://cdn.example.com/unit2b-kitchen.jpg" }
]

Marketplaces

Setting enabled: false unpublishes the listing. Only explicitly listed entries are affected; others retain their current state.

9. Enum Value Reference

Unit Type

Rental Space

Rent Payment Frequency

Renewal Frequency

10. Response Format

Envelope

{
  "success": true,
  "report_type": "showings",
  "company_id": 123,
  "count": 45,
  "data": [ ... ]
}

Data types

11. Error Reference

Validation Error Format (422)

{
  "error": "Unprocessable Entity",
  "message": "Validation failed. See 'details' for field-level errors.",
  "details": [
    "\"name\" is required.",
    "\"unit_type\" invalid: \"studio\". Valid values: [\"apartment\", \"house\", ...]"
  ]
}

12. Code Examples

JavaScript (fetch)

const authHeaders = {
  "Authorization": `Bearer ${API_TOKEN}`,
  "X-Company-Password": COMPANY_PASSWORD,
};

// Get showings report
const params = new URLSearchParams({ company_id: COMPANY_ID, start_date: "2024-01-01T00:00:00" });
const res = await fetch(`${BASE_URL}/reports/showings?${params}`, { headers: authHeaders });
const showings = await res.json();

// Create a property
const createRes = await fetch(`${BASE_URL}/properties`, {
  method: "POST",
  headers: { ...authHeaders, "Content-Type": "application/json" },
  body: JSON.stringify({
    company_id: COMPANY_ID,
    password: COMPANY_PASSWORD,
    property: { name: "Unit 2B", address: "456 Oak Ave", city: "Toronto",
      province_state: "ON", country: "Canada", rent_amount: "2100", bedrooms: 2, bathrooms: 1 }
  }),
});
const { property_id } = await createRes.json(); // Save this!

Python

import requests

auth_headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "X-Company-Password": COMPANY_PASSWORD,
}

# Get leads report
response = requests.get(f"{BASE_URL}/reports/leads",
    headers=auth_headers,
    params={"company_id": COMPANY_ID, "start_date": "2024-01-01T00:00:00"})
leads = response.json()

# Create a property
response = requests.post(f"{BASE_URL}/properties",
    headers={**auth_headers, "Content-Type": "application/json"},
    json={
        "company_id": COMPANY_ID, "password": COMPANY_PASSWORD,
        "property": { "name": "Unit 2B", "address": "456 Oak Ave", "city": "Toronto",
            "province_state": "ON", "country": "Canada", "rent_amount": "2100" }
    })
property_id = response.json()["property_id"]

PHP

// Get properties report
$ch = curl_init($BASE_URL . "/reports/properties?company_id=" . $COMPANY_ID);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $API_TOKEN",
        "X-Company-Password: $COMPANY_PASSWORD",
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

// Create a property
$payload = json_encode(["company_id" => $COMPANY_ID, "password" => $COMPANY_PASSWORD,
    "property" => ["name" => "Unit 2B", "address" => "456 Oak Ave",
        "city" => "Toronto", "province_state" => "ON", "country" => "Canada"]]);
$ch = curl_init($BASE_URL . "/properties");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $API_TOKEN", "Content-Type: application/json"],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

13. Testing with Postman

Step 1 — Get the endpoint URL

cd reports-api-service
serverless info --stage production

Look for the endpoints section. The URL will look like: https://uvciw58bnh.execute-api.ca-central-1.amazonaws.com/production

Step 2 — Create an environment

Step 3 — GET showings

1. Method: GET · URL: {{base_url}}/reports/showings
2. Params: company_id → {{company_id}} · start_date → 2024-01-01T00:00:00
3. Headers: Authorization → Bearer {{api_token}}
4. Headers: X-Company-Password → {{company_password}}
5. Click Send

Step 4 — POST property

1. Method: POST · URL: {{base_url}}/properties
2. Headers: Authorization → Bearer {{api_token}} · Content-Type → application/json
3. Body → raw → JSON: paste your create property payload
4. Click Send

14. Troubleshooting

401 — Token length mismatch

If you see "The provided token does not match the expected token" with a debug field showing token_received_length: 32 and token_expected_length: 48, your token is being truncated. Verify you are copying the full 48-character token — check for line breaks or truncation in your environment variable or config file.

401 — Token not working

• Verify Content-Type: application/json is set.
• Ensure you are using the correct token for the right stage (dev and production tokens are different).
• Check CloudWatch logs: serverless logs -f reportsApi --stage production --tail

401 — Company password not working

Confirm the passwordapi field is set in Leasey dashboard → Settings → API Access.

400 — company_id must be an integer

Send as a number: ?company_id=123 ✅   ?company_id="123" ❌. In Postman query params, type the value without quotes.

422 — Invalid enum value

You sent a value not in the allowed enum list. Common mistakes: "condo", "studio", "loft", "shared room", "private room", "semi-monthly" — none of these exist. Check the Enum Values section for the exact accepted values.

CORS errors in browser

The API allows all origins. CORS errors are almost always caused by a missing Authorization header triggering a 401 before CORS preflight headers are sent. Check auth headers first.

500 — Internal Server Error

Check CloudWatch logs for the specific stack trace: serverless logs -f reportsApi --stage production --tail. Common causes: database connection timeout (Lambda cold start), invalid SQL from a malformed date parameter.

15. Best Practices

Support

Leasey External API v2.0 — © 2024 Lease.ai. All rights reserved.