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

# Integration api

# Integration API Reference Guide

This document provides a comprehensive reference for the Monument Integration API. The API allows third-party systems to integrate with Monument's facility management platform to access and manage core business entities.

## Base URL

All endpoints are prefixed with:

```
https://public-api.{env}.monument.io/api/:portfolio/portfolios/v1
```

Where `:portfolio` is the defined database prefix (e.g., `abc_selfstorage`).

## Authentication

All requests require an API key in the header:

```
x-api-key: YOUR_API_KEY
```

**Important**: API keys are managed and must be obtained from Monument. Contact Monument Integrations Support Team to request an API key for your integration.
Email: [integrationsupport@monument.io](mailto:integrationsupport@monument.io)

## Authorization

Not all API keys will have access to all endpoints. Access is controlled through resource-based permissions that are configured per API key. Each endpoint requires specific access permissions:

* **READ** access: Required to retrieve data from endpoints
* **WRITE** access: Required to create or update data

### Unauthorized Endpoint Access Response

When an API key does not have the required permissions for an endpoint, the API will return:

**Status Code**: `401 Unauthorized`

**Response Body**:

```json theme={null}
{
  "statusCode": 401,
  "message": "You must have :accessType access to :resource to use this endpoint.Please contact Monument."
}
```

### Unauthorized Portfolio Access Response

When an API key does not have the required permissions for a portfolio, the API will return:

**Status Code**: `404 Not found`

**Response Body**:

```json theme={null}
{
  "statusCode": 404,
  "message": "Portfolio does not exist."
}
```

**Common Scenarios**:

* API key lacks READ permission for the requested resource type
* API key lacks WRITE permission for create/update operations
* API key is restricted from accessing specific portfolios (whitelist/blacklist configuration)

If you receive a 401 Unauthorized/404 Not found response, verify that your API key has been granted the appropriate permissions for the endpoint you're attempting to access and that the path is correct. Contact Monument Integrations Support Team to request additional permissions if needed.

## API Structure

The Integration API follows a consistent two-step pattern for retrieving entity data:

### Step 1: Get UUIDs

First, retrieve the UUIDs of entities you want to fetch. This endpoint supports filtering by date ranges and other criteria:

```
GET /api/:portfolio/portfolios/v1/{entity}/uuids
```

**Query Parameters**:

* `updatedAt.lessOrEqual` (optional): Filter entities updated on or before this date-time
* `updatedAt.greaterOrEqual` (optional): Filter entities updated on or after this date-time
* `createdAt.lessOrEqual` (optional): Filter entities created on or before this date-time
* `createdAt.greaterOrEqual` (optional): Filter entities created on or after this date-time
* Additional entity-specific filters may be available

**Response**: Array of UUID strings, ordered by most recently updated first

**Example**:

```json theme={null}
[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001",
  "123e4567-e89b-12d3-a456-426614174002"
]
```

### Step 2: Get Details by UUIDs

After obtaining UUIDs, retrieve the full details for those entities:

```
POST /api/:portfolio/portfolios/v1/{entity}/get_by_uuids
```

**Request Body**:

```json theme={null}
{
  "{entity}Uuids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ]
}
```

**Response**: Array of entity detail objects

**Example**:

```json theme={null}
[
  {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Example Entity"
    // ... additional fields
  }
]
```

### Why This Pattern?

This two-step pattern provides several benefits:

1. **Efficient Filtering**: The UUID endpoint supports complex filtering without transferring large payloads
2. **Selective Retrieval**: Fetch only the entities you need by their UUIDs
3. **Pagination Support**: Handle large datasets by chunking UUID requests (see [Entity Limits](#entity-limits))
4. **Performance**: UUID lists are lightweight, allowing you to determine what data to fetch before making heavier detail requests

## Entity Limits

The Integration API enforces limits on the number of entities that can be retrieved in a single request to ensure optimal performance and prevent timeouts.

### Maximum UUIDs Per Request

**Limit**: A maximum of **1,000 UUIDs** can be included in a single `get_by_uuids` request.

**Error Response**: If you exceed this limit, the API will return:

**Status Code**: `400 Bad Request`

**Response Body**:

```json theme={null}
{
  "statusCode": 400,
  "message": ["Too many uuids"],
  "error": "Bad Request"
}
```

## Core Entities

The Integration API provides access to the following core business entities:

### Portfolio

Represents the top-level organization that owns facilities and manages operations.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/portfolios` - Get portfolio information

### Facility

Represents a physical storage facility location.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/uuids` - Get facility UUIDs
* `POST /api/:portfolio/portfolios/v1/facilities/get_by_uuids` - Get facility details by UUIDs

**Key Fields**:

* `facilityUuid`: Unique identifier
* `facilityName`: Name of the facility
* `address`: Physical address
* `phone`: Contact phone number
* `email`: Contact email
* `amenities`: Array of available amenities
* `operatingHours`: Facility operating schedule

### Lead

Represents a potential customer who has expressed interest in renting a unit but has not yet completed the rental process.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/leads/uuids` - Get lead UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/leads/get_by_uuids` - Get lead details by UUIDs

**Key Fields**:

* `leadUuid`: Unique identifier
* `primaryPersonUuid`: UUID of the primary contact person
* `facilityUuid`: Associated facility
* `unitGroupUuid`: Selected unit group
* `leadStatus`: Current status (e.g., OPEN, PENDING, CONVERTED)
* `leadType`: Type of lead (PERSONAL or BUSINESS)

### Tenant

Represents an active customer account that has completed the rental process and has an active lease.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/tenants/uuids` - Get tenant UUIDs
* `POST /api/:portfolio/portfolios/v1/tenants/get_by_uuids` - Get tenant details by UUIDs

**Key Fields**:

* `accountUuid`: Unique identifier (also referred to as tenantUuid)
* `primaryPersonUuid`: UUID of the primary contact person
* `businessName`: Business name (for business accounts)
* `taxId`: Tax identification number (for business accounts)
* `accountStatus`: Current account status

### Unit Rental Record

Represents an active rental agreement between a tenant and a facility for a specific unit.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/uuids` - Get rental record UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/get_by_uuids` - Get rental record details by UUIDs

**Key Fields**:

* `unitRentalRecordUuid`: Unique identifier
* `accountUuid`: Associated tenant account
* `unitUuid`: Associated unit
* `facilityUuid`: Associated facility
* `status`: Rental status (e.g., ACTIVE, VACATED, TRANSFERRED)
* `startDate`: Lease start date
* `endDate`: Lease end date (if applicable)

### Person

Represents an individual person who may be associated with leads, tenants, or other entities as a contact.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/people/uuids` - Get person UUIDs
* `POST /api/:portfolio/portfolios/v1/people/get_by_uuids` - Get person details by UUIDs

**Query Parameters** (for UUIDs endpoint):

* `onlyPrimaryContacts` (boolean, optional): If true, only return persons who are the primaryPersonUuid for accounts or leads

**Key Fields**:

* `personUuid`: Unique identifier
* `firstName`: First name
* `lastName`: Last name
* `email`: Email address
* `phone`: Phone number
* `addressLine1`, `addressLine2`, `city`, `state`, `zip`, `country`: Address information

### Delinquencies

Represents accounts that are past due on payments.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/delinquencies/uuids` - Get delinquency UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/delinquencies/get_by_uuids` - Get delinquency details by UUIDs

**Key Fields**:

* `delinquencyUuid`: Unique identifier
* `accountUuid`: Associated tenant account
* `unitRentalRecordUuid`: Associated rental record
* `delinquencyStage`: Current delinquency stage
* `amountDue`: Outstanding amount
* `daysPastDue`: Number of days past due

### Ledger Entries

Represents individual line items on a rental record's ledger, including charges, payments, and adjustments.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/ledgerEntries/uuids` - Get ledger entry UUIDs for a rental record
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/ledgerEntries/get_by_uuids` - Get ledger entries by UUIDs

**Key Fields**:

* `lineItemLedgerUuid`: Unique identifier
* `unitRentalRecordUuid`: Associated rental record
* `itemTypeUuid`: Type of charge or payment
* `amount`: Transaction amount
* `dateCreated`: Transaction date
* `description`: Transaction description

### Item Types

Represents types of charges, fees, and services that can be applied to rental records (e.g., rent, late fees, additional services).

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/itemTypes/uuids` - Get item type UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/itemTypes/get_by_uuids` - Get item types by UUIDs

**Key Fields**:

* `itemTypeUuid`: Unique identifier
* `itemTypeName`: Name of the item type
* `description`: Description
* `category`: Category (e.g., RENT, SERVICES, FEES)
* `isRecurring`: Whether the item is recurring
* `isTaxable`: Whether the item is subject to tax
* `feeType`: Fee calculation type (FIXED\_AMOUNT, PERCENTAGE, etc.)

### Amenities

Represents features and services available at facilities or for specific units (e.g., climate control, drive-up access, 24/7 access).

**Note**: Amenities are typically included in facility and unit detail responses rather than having dedicated endpoints. They appear as arrays within facility and unit group responses.

**Key Fields** (when included in responses):

* `amenityUuid`: Unique identifier
* `name`: Name of the amenity
* `description`: Description
* `present`: Boolean indicating if the amenity is available

### Coverage

Represents insurance coverage options available to tenants.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/coverageHistory/uuids` - Get coverage history UUIDs
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/coverageHistory/get_by_uuids` - Get coverage history by UUIDs

**Key Fields**:

* `coverageUuid`: Unique identifier
* `provider`: Coverage provider name
* `premiumInPennies`: Premium amount in pennies
* `coverageAmountInPennies`: Coverage amount in pennies
* `description`: Description of coverage

### Payment Profiles

Represents stored payment methods (credit cards or bank accounts) associated with tenant accounts.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/paymentProfiles/uuids` - Get payment profile UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/paymentProfiles/get_by_uuids` - Get payment profiles by UUIDs

**Key Fields**:

* `paymentProfileUuid`: Unique identifier
* `accountUuid`: Associated tenant account
* `paymentType`: Type of payment method (CREDIT/DEBIT, ACH)
* `lastFour`: Last four digits of the payment method
* `isDefault`: Whether this is the default payment method
* `autopayEnabled`: Whether autopay is enabled

### Notes

Represents notes and comments associated with various entities (leads, tenants, rental records, etc.).

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/notes/uuids` - Get note UUIDs
* `POST /api/:portfolio/portfolios/v1/notes/get_by_uuids` - Get notes by UUIDs
* `POST /api/:portfolio/portfolios/v1/notes/tenants/:accountUuid` - Create note for tenant
* `POST /api/:portfolio/portfolios/v1/notes/leads/:leadUuid` - Create note for lead

**Key Fields**:

* `noteUuid`: Unique identifier
* `entityType`: Type of entity the note is associated with (TENANT, LEAD, etc.)
* `entityUuid`: UUID of the associated entity
* `content`: Note content/text
* `createdAt`: Creation timestamp
* `createdBy`: User who created the note

### Unit Groups

Represents collections of similar storage units that share the same characteristics (size, features, pricing).

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/unitGroups/uuids` - Get unit group UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/unitGroups/get_by_uuids` - Get unit groups by UUIDs

**Key Fields**:

* `unitGroupUuid`: Unique identifier
* `description`: Description of the unit group
* `unitGroupDepth`, `unitGroupWidth`, `unitGroupHeight`: Unit dimensions
* `amenities`: Array of available amenities
* `availableUnitCount`: Number of available units
* `unitCount`: Total number of units in the group
* `currentStreetRate`: Current street rate in pennies
* `currentWebRate`: Current web rate in pennies

### Units

Represents individual physical storage units within a facility.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/units/uuids` - Get unit UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/units/get_by_uuids` - Get units by UUIDs

**Key Fields**:

* `unitUuid`: Unique identifier
* `unitName`: Unit identifier (e.g., "A-101")
* `facilityUuid`: Associated facility
* `unitGroupUuid`: Associated unit group
* `occupancyStatus`: Current status (AVAILABLE, OCCUPIED, RESERVED, etc.)

### Vehicles

Represents vehicles associated with tenant accounts (for vehicle/RV storage).

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/vehicles/uuids` - Get vehicle UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/vehicles/get_by_uuids` - Get vehicles by UUIDs

**Key Fields**:

* `vehicleUuid`: Unique identifier
* `accountUuid`: Associated tenant account
* `vehicleType`: Type of vehicle
* `make`: Vehicle make
* `model`: Vehicle model
* `vinNumber`: Vehicle identification number
* `licensePlateNumber`: License plate number

### Tasks

Represents tasks and to-dos associated with a facility, optionally linked to a specific lead or tenant.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/tasks/uuids` - Get task UUIDs for a facility
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/tasks/get_by_uuids` - Get task details by UUIDs
* `POST /api/:portfolio/portfolios/v1/facilities/:facilityUuid/tasks` - Create a task for a facility

**Query Parameters** (for UUIDs endpoint):

* `taskCategory` (enum: LEADS, TENANTS, DELINQUENCIES, OTHER, optional): Filter tasks by category
* `completed` (string, optional): Filter by completion status — `"true"` for completed only, `"false"` for incomplete only; omit for all
* `createdAt.greaterOrEqual` (ISO 8601, optional): Filter tasks created on or after this date-time
* `createdAt.lessOrEqual` (ISO 8601, optional): Filter tasks created on or before this date-time

**Note**: When creating a task, the `taskCategory` determines which UUID is required: `LEADS` requires `leadUuid`; `TENANTS`, `DELINQUENCIES`, and `OTHER` require `accountUuid`. The other UUID field must be omitted.

**Key Fields**:

* `taskUuid`: Unique identifier
* `name`: Task name (max 35 characters)
* `description`: Optional task description (max 100 characters)
* `category`: Task category (LEADS, TENANTS, DELINQUENCIES, OTHER)
* `dueDate`: Due date (day-only format)
* `facilityUuid`: Associated facility
* `facilityName`: Facility name
* `leadUuid`, `leadFirstName`, `leadLastName`: Associated lead details (populated when `category` is LEADS)
* `tenantUuid`, `tenantFirstName`, `tenantLastName`: Associated tenant details (populated when `category` is TENANTS, DELINQUENCIES, or OTHER)
* `completedAt`: Timestamp when the task was completed, null if incomplete
* `completedByUserUuid`: UUID of the user who completed the task
* `createdAt`: Creation timestamp

### Move-Out Requests

Represents a scheduled move-out request against an active unit rental record. Each rental record has at most one active request at a time.

**Endpoints**:

* `PUT /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/move-out` - Schedule a move-out request, or update the existing active request
* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/move-out` - Get the active scheduled move-out request (responds `404` when there is none)
* `DELETE /api/:portfolio/portfolios/v1/facilities/:facilityUuid/rentalRecords/:unitRentalRecordUuid/move-out` - Cancel the active scheduled move-out request (idempotent — succeeds even when no active request exists)

**Request Body** (for `PUT`):

* `moveOutReasonUuid` (string, required): UUID of the move-out reason
* `moveOutDate` (date `YYYY-MM-DD`, required): Requested move-out date

**Note**: `moveOutReasonUuid` must be one of the values returned by the Move-Out Reasons endpoint.

**Key Fields**:

* `moveOutRequestUuid`: Unique identifier of the move-out request
* `unitRentalRecordUuid`: Associated unit rental record
* `moveOutReasonUuid`: Associated move-out reason
* `requestedMoveOutDate`: The requested move-out date

### Move-Out Reasons

Represents the active move-out reasons — the valid `moveOutReasonUuid` options when scheduling a move-out request.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/move-out/reasons` - Get active move-out reasons

**Key Fields**:

* `moveOutReasonUuid`: Unique identifier of the move-out reason
* `reasonDescription`: Human-readable description of the move-out reason

### Insurance Summary

Provides per-facility insurance enrollment and occupancy aggregates for a date range. Returns one row per scoped facility; out-of-scope facilities are dropped, and an empty scope returns an empty array.

**Endpoints**:

* `POST /api/:portfolio/portfolios/v1/summary/insurance` - Get insurance enrollment/occupancy summary

**Request Body**:

* `facilityUuids` (array of UUID, required): Facility UUIDs to aggregate over (1–1000)
* `startDate` (ISO date, required): Inclusive start of the reporting period
* `endDate` (ISO date, required): Inclusive end of the reporting period

**Key Fields** (one row per facility):

* `facilityUuid`: Facility UUID this row aggregates
* `startDate`, `endDate`: Reporting period, echoed from the request
* `totalActiveLeases`: Distinct rentals active at any point in the period
* `totalInsuredLeases`: Distinct rentals with non-private coverage active at any point in the period
* `pctInsured`: `totalInsuredLeases / totalActiveLeases * 100`, rounded to 2 decimals; `0` when there are no active leases
* `newMoveIns`: Rentals whose start date falls within the period
* `newMoveInsInsured`: Of the new move-ins, those with non-private coverage
* `pctNewMoveInsInsured`: `newMoveInsInsured / newMoveIns * 100`, rounded to 2 decimals; `0` when there are no new move-ins

### Overlock Codes

Represents the active overlock/physical-lock codes for a unit, regardless of provider. A unit may have more than one active lock.

**Endpoints**:

* `GET /api/:portfolio/portfolios/v1/facilities/:facilityUuid/units/:unitUuid/overlock-code` - Get the active overlock codes for a unit

**Key Fields**:

* `lockCode`: The active overlock/physical-lock code for the unit
* `externalLockId`: The external (provider) lock identifier
* `provider`: The physical lock provider (e.g., `DaVinci`)
* `unitUuid`: UUID of the unit
* `unitRentalRecordUuid`: UUID of the unit rental record the lock is associated with, or `null` (e.g., a lock on a vacant unit)

## Error Handling

### Common HTTP Status Codes

* `200 OK`: Request successful
* `201 Created`: Resource created successfully
* `400 Bad Request`: Invalid request data (e.g., too many UUIDs, invalid input format)
* `401 Unauthorized`: API key lacks required permissions for the endpoint
* `403 Forbidden`: Access denied (e.g., portfolio access restrictions)
* `404 Not Found`: Resource not found
* `500 Internal Server Error`: Server error

### Handling Errors

1. **Check Status Code**: Determine the type of error from the HTTP status code
2. **Read Error Message**: The `message` field provides specific details about what went wrong
3. **Retry Logic**: For transient errors (5xx), implement exponential backoff retry logic
4. **Contact Support**: For persistent authorization errors (401/403), contact Monument Integrations Support Team to verify API key permissions

## Best Practices

1. **Use Date Filters**: When fetching UUIDs, use date filters to limit the dataset and reduce processing time
2. **Implement Chunking**: Always split large UUID arrays into chunks of 1,000 when calling `get_by_uuids`
3. **Cache UUIDs**: UUID lists change less frequently than detail data - consider caching UUID responses
4. **Handle Rate Limits**: Implement rate limiting and retry logic to handle API throttling gracefully
5. **Monitor Errors**: Log and monitor 401/403 errors to identify permission issues early
6. **Use Appropriate Filters**: Leverage entity-specific filters (e.g., `onlyPrimaryContacts` for people) to reduce unnecessary data transfer

## Questions?

If you have questions about any endpoint or need clarification on the API behavior, please contact the Monument Integrations Support Team.
Email: [integrationsupport@monument.io](mailto:integrationsupport@monument.io)