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: [email protected]

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:

{
  "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:

{
  "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:

[
  "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:

{
  "{entity}Uuids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ]
}

Response: Array of entity detail objects Example:

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

Why This Pattern?

This two-step pattern provides several benefits:

Efficient Filtering: The UUID endpoint supports complex filtering without transferring large payloads
Selective Retrieval: Fetch only the entities you need by their UUIDs
Pagination Support: Handle large datasets by chunking UUID requests (see Entity Limits)
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:

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

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

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

Best Practices

Use Date Filters: When fetching UUIDs, use date filters to limit the dataset and reduce processing time
Implement Chunking: Always split large UUID arrays into chunks of 1,000 when calling get_by_uuids
Cache UUIDs: UUID lists change less frequently than detail data - consider caching UUID responses
Handle Rate Limits: Implement rate limiting and retry logic to handle API throttling gracefully
Monitor Errors: Log and monitor 401/403 errors to identify permission issues early
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: [email protected]

​Integration API Reference Guide

​Base URL

​Authentication

​Authorization

​Unauthorized Endpoint Access Response

​Unauthorized Portfolio Access Response

​API Structure

​Step 1: Get UUIDs

​Step 2: Get Details by UUIDs

​Why This Pattern?

​Entity Limits

​Maximum UUIDs Per Request

​Core Entities

​Portfolio

​Facility

​Lead

​Tenant

​Unit Rental Record

​Person

​Delinquencies

​Ledger Entries

​Item Types

​Amenities

​Coverage

​Payment Profiles

​Notes

​Unit Groups

​Units

​Vehicles

​Error Handling

​Common HTTP Status Codes

​Handling Errors

​Best Practices

​Questions?

Integration API Reference Guide

Base URL

Authentication

Authorization

Unauthorized Endpoint Access Response

Unauthorized Portfolio Access Response

API Structure

Step 1: Get UUIDs

Step 2: Get Details by UUIDs

Why This Pattern?

Entity Limits

Maximum UUIDs Per Request

Core Entities

Portfolio

Facility

Lead

Tenant

Unit Rental Record

Person

Delinquencies

Ledger Entries

Item Types

Amenities

Coverage

Payment Profiles

Notes

Unit Groups

Units

Vehicles

Error Handling

Common HTTP Status Codes

Handling Errors

Best Practices

Questions?