Welcome to the Prime Management API. This API allows you to manage storage rentals, reservations, and more.

Rental API Instructions

Overview

The Rental API allows you to create and finalize rentals using GraphQL mutations. This guide explains:

• How to create a rental
• How to finalize a rental
• What happens behind the scenes during each process

---

1️⃣ Creating a Rental

To create a rental, use the createRental mutation. This process involves:

Tenant Handling

• Find or Create Tenant:

  • If a tenant ID is provided, the system retrieves the tenant.
  • If tenant details are provided, it attempts to find or create the tenant.
  • Otherwise, a new tenant is created using basic details (first name, last name, email, phone).

• Location Population:

  • If a locationIdentifier is provided, the system fetches and populates the location details.

• Sitelink Integration & Elasticsearch:

  • Checks for the tenant in MongoDB and Sitelink, updates if found, and pushes tenant data to Elasticsearch.

• Ably Notification:

  • A message is sent via the Ably channel to broadcast the tenant creation event.

Reservation Creation

• Location & Tenant Population:

  • The system retrieves location details and populates tenant information (either provided or newly created).

• Unit Availability:

  • Verifies unit availability; if the selected unit isn’t available, assigns the next available unit.

• Expiration Date Setting:

  • Sets the expiration date depending on whether the reservation is an inquiry (15 days) or a standard reservation (72 hours).

• Sitelink Reservation:

  • Creates the reservation in Sitelink unless bypassed, passing additional parameters like rental type.

• Elasticsearch & Ably:

  • Pushes the reservation to Elasticsearch and notifies via the Ably channel.

Email & Note Scheduling

• Waiting List or Reservation Notification:
  • If it’s a join waiting list, schedules a waiting list email (scheduleWaitingListEmail) and a reservation note (scheduleReservationNote).
  • Otherwise, schedules a reservation email (scheduleReservationEmail) along with a corresponding note.

Mutation Example

mutation createRental($input: CreateRentalInput!) {
  createRental(input: $input) {
    tenant {
      id
      firstName
      lastName
      email
      phone
    }
    reservation {
      id
      neededAt
      reservationStatus
      sitelinkId
      quotedRate
    }
  }
}

VARIABLES

{
  "input": {
    "tenant": {
      "company": "",
      "isCompany": false,
      "firstName": "Russell",
      "lastName": "Jones",
      "email": "test+1@test.com",
      "address": "",
      "address2": "",
      "city": "",
      "region": "",
      "postalCode": "",
      "country": "",
      "phone": "(123) 123-1231",
      "mobilePhone": ""
    },
    "neededAt": "2025-03-11T04:00:00.000Z",
    "quotedRate": 75,
    "reservationType": "LEAD",
    "locationIdentifier": "LPLANETSETUP",
    "unitId": "679189d7d02039930c155e7c",
    "concessionId": -999,
    "insuranceId": -999
  }
}

Payload Example:

{
  "data": {
    "createRental": {
      "reservation": {
        "id": "67d037a752befe01f323769e",
        "reservationSource": null,
        "reservationStatus": "ACTIVE",
        "reservationType": null,
        "sitelinkId": "2191625",
        "unit": {
          "id": "679189d7d02039930c155e7c",
          "sitelinkId": "162195"
        }
      },
      "tenant": {
        "id": "6797c2402cb24b5fec192b12",
        "sitelinkId": "2862485"
      }
    }
  }
}

Required Fields for Lead Creation

Field	Required?	Description
locationIdentifier	✅ Yes	The location where the lead is created.
reservationStatus	✅ Yes	Should be ACTIVE for new leads.
reservationType	✅ Yes	Must be set to LEAD.
reservationSource	✅ Yes	Specifies the source of the lead (e.g., WEB).
neededAt	✅ Yes	Timestamp for when the lead is needed.
tenant.firstName	✅ Yes	Lead’s first name.
tenant.lastName	✅ Yes	Lead’s last name.
tenant.email	✅ Yes	Lead’s email address.
unitId	✅ Yes	The ID of the selected unit size.
phone	⛔ No	Optional phone number.

2️⃣ Finalizing a Rental

To finalize a rental, use the finalizeRental mutation. This process includes:

Location Retrieval

• The location is fetched using the provided locationIdentifier.

Move-In Creation

Data Gathering

• Concurrently retrieves details for the unit, tenant, location, and reservation.

Move-In Record Creation

• Sets the move-in start date and calculates an end date (defaults to one month later if not provided).
• Calls Sitelink’s createMoveIn, which serializes the input, calls the API (MoveInWithDiscount_v5), and deserializes the response.

Proof of Insurance (Optional)

• If proof of insurance is provided, it is sent to Sitelink with details like insurer name and provider phone.

Reservation Update

• Re-imports the original reservation to update its state based on the move-in.

Background CRON Job Scheduling

Tenant Update

• Schedules a CRON job (scheduleUpdateTenant) to update tenant details after 30 seconds.

Tenant Billing Update

• Schedules another CRON job (scheduleUpdateTenantBilling) to update tenant billing information after 30 seconds.

Mutation Example

mutation {
  finalizeRental(input: $finalizeRentalInput) {
    leaseNumber
    ledgerId
    reservation {
      id
      neededAt
    }
  }
}

VARIABLES

{
  "finalizeRentalInput": {
    "locationIdentifier": "LPLANETSETUP",
    "tenantId": "6797c2402cb24b5fec192b12",
    "unitId": "679189d7d02039930c155e7c",
    "concessionId": 0,
    "insuranceId": -999,
    "paymentAmount": 75.0,
    "reservationId": "67d037a752befe01f323769e",
    "moveInDate": "2025-03-11T04:00:00.000Z",
    "creditCardType": "Visa",
    "creditCardNumber": "4111 1111 1111 1111",
    "expirationDate": "12/26",
    "creditCardCVV": "123",
    "billingName": "Russell Jones",
    "billingAddress": "123 Main St",
    "billingZipCode": "12345",
    "autoBillType": "CreditCard"
  }
}

RESPONSE

{
  "data": {
    "finalizeRental": {
      "leaseNumber": 713,
      "ledgerId": 1852539,
      "reservation": {
        "id": "67d037a752befe01f323769e",
        "neededAt": "2025-03-11T04:00:00.000Z"
      }
    }
  }
}

Required fields

Field	Required?	Description
locationIdentifier	✅ Yes	The location where the rental is finalized.
tenantId	✅ Yes	The ID of the tenant.
reservationId	✅ Yes	The ID of the reservation.
moveInDate	✅ Yes	Date of move-in.
creditCardType	✅ Yes	Type of credit card (VISA, MASTERCARD, etc.).
creditCardNumber	✅ Yes	Credit card number for payment.
expirationDate	✅ Yes	Credit card expiration date (MM/YY).
creditCardCVV	✅ Yes	CVV code for credit card verification.
isEnableAutopay	✅ Yes	Whether autopay should be enabled.
paymentAmount	✅ Yes	Amount being charged.
leaseNumber	✅ Yes	Generated lease number after rental finalization.
billingName	⛔ No	Name on the billing information.
insuranceId	⛔ No	ID of the selected insurance plan.
concessionId	⛔ No	Discount applied to rental.

3️⃣ Behind the Scenes

Tenant Service

• Tenant Creation & Update:
  • Populates location details if locationIdentifier is provided.
  • Checks for an existing tenant in MongoDB and Sitelink; updates if found or creates a new tenant if not.
• Sitelink Integration:
  • Imports or creates the tenant in Sitelink and attaches Sitelink-specific attributes.
• Elasticsearch & Ably:
  • Pushes tenant data to Elasticsearch and sends an update message via the Ably channel.

Reservation Service

• Reservation Creation:
  • Retrieves and sets location and tenant details.
  • Checks unit availability and sets expiration dates.
  • Integrates with Sitelink to create a reservation and enriches the reservation data.
• Notifications:
  • Pushes reservation data to Elasticsearch and sends notifications via Ably.
• Email & Note Scheduling:
  • Waiting List: Schedules waiting list emails and notes when applicable.
  • Standard Reservation: Schedules reservation emails and logs a reservation note.

Email & Note Scheduling Functions

• Mailing List:
  • scheduleWaitingListEmail enqueues a job to send a waiting list email (no delay, 3 retries).
• Reservation Email:
  • scheduleReservationEmail enqueues a job to send a reservation confirmation email.
• Reservation Note:
  • scheduleReservationNote enqueues a job to log a reservation note.
• Move-In Bulletin & Emails:
  • After move-in creation, a bulletin is scheduled (scheduleMoveInBulletin) and both rental (scheduleRentalEmail) and move-in emails (scheduleMoveInEmail) are sent.
• Tenant Note:
  • scheduleTenantNote logs a tenant note for the move-in event.

Move-In Process

• Create Move-In:
  • Fetches unit, tenant, location, and reservation concurrently.
  • Sets the end date (defaults to one month later if not provided).
  • Invokes Sitelink’s createMoveIn (serializing input, API call, deserializing response).
• Post Move-In Actions:
  • Schedules a move-in bulletin, rental email, move-in email, and a tenant note to record the event.

Background CRON Scheduling

• Tenant Update:
  • scheduleUpdateTenant creates a CRON job that updates tenant information after 30 seconds.
• Tenant Billing Update:
  • scheduleUpdateTenantBilling creates a CRON job that updates tenant billing information after 30 seconds.
• Job Identification:
  • Each job is assigned a unique identifier using the current timestamp and a UUID.

Reservation API Instructions

Overview

The Reservation API provides functionality for creating, updating, retrieving, and deleting reservations. This document provides step-by-step instructions for creating a reservation.

---

1️⃣ Creating a Reservation

When creating a reservation, the system performs the following steps:

Step 1: Populate Location

• If a locationIdentifier is provided:
  • The system fetches the corresponding location details using LocationsService.findByIdentifier.
  • The fetched location is then added to the reservation input.

Step 2: Populate Tenant

• If a tenantId is provided:
  • The system retrieves tenant details using TenantsService.findOne.
• If no tenant is provided:
  • A new tenant is created using basic tenant details (first name, last name, email, phone, and company) via TenantsService.create.

Step 3: Verify Unit Availability

• If Sitelink integration is enabled (i.e. options?.bypassSitelink is not true):
  • The system checks unit availability using UnitsService.availability with the provided locationIdentifier and unitId.
  • Unit Assignment:
    • If the selected unit isn’t available and there is an alternative (i.e. nextAvailableUnit exists), the alternative unit is assigned.
    • If no available unit is found, an error is thrown.

Step 4: Populate Unit

• If a unitId is provided and the unit is not yet populated:
  • The system retrieves the unit details using UnitsService.findOne.

Step 5: Set Reservation Expiration

• The expiration date is determined based on whether the reservation is an inquiry:
  • Inquiry: Expiration is set to 15 days from the start date.
  • Standard Reservation: Expiration is set to 72 hours from the start date.
• The calculation is performed using the dayjs library.

Step 6: Push Reservation to Sitelink

• If Sitelink integration is enabled:
  • The reservation is pushed to Sitelink using SitelinkService.createReservation.
  • Required parameters such as locationIdentifier, sitelinkTenantId, sitelinkUnitId, and rentalType are passed.

Step 7: Create Reservation in MongoDB

• The reservation is created using the Mongoose model’s create method.
• The input data is merged with Sitelink attributes (if available) and saved.
• After creation, the reservation document is populated with related fields (i.e. location, tenant, and unit).

Step 8: Error Handling

• If the reservation is not successfully created, an error is thrown.

Step 9: Push Reservation to Elasticsearch

• The created reservation is indexed in Elasticsearch using ElasticsearchService.update.
• Any errors during this process are caught and logged (with plans to forward them to Sentry).

Step 10: Push Notification via Ably

• A notification message is sent via the Ably channel using AblySchedulingService.scheduleSendMessage to inform other systems of the new reservation.

Step 11: Email and Note Scheduling

• If Sitelink integration is enabled:
  • Waiting List Scenario:
    • If isJoinWaitingList is true, a waiting list email is scheduled using EmailsSchedulingService.scheduleWaitingListEmail.
    • A corresponding reservation note is added via NotesSchedulingService.scheduleReservationNote.
  • Standard Reservation:
    • If a valid neededAt date is provided and neither isJoinWaitingList nor isInquiry is true, a reservation email is scheduled using EmailsSchedulingService.scheduleReservationEmail.
    • A reservation note is then added.

Step 12: Return Created Reservation

• The final created reservation is returned as the output of the API call.

---

Example Mutation

Below is an example GraphQL mutation for creating a reservation:

mutation createReservation($createReservationInput: CreateReservationInput!) {
  createReservation(input: $createReservationInput) {
    id
    sitelinkId
    tenant {
      id
      firstName
      lastName
    }
    location {
      id
      identifier
      name
    }
    unit {
      id
      name
    }
  }
}

VARIABLES

{
  "createReservationInput": {
    "locationIdentifier": "LPLANETSETUP",
    "tenantId": null,
    "unitId": "679ac18058e808bfa19f7511",
    "concessionId": 42182,
    "quotedRate": 86.87,
    "firstName": "Russell",
    "lastName": "Jones",
    "phone": "(123) 123-1231",
    "email": "test+1@test.com",
    "neededAt": "2025-03-11T15:44:10.510Z",
    "isActiveMilitary": false,
    "company": "",
    "isJoinWaitingList": false
  }
}

RESPONSE

{
  "data": {
    "createReservation": {
      "id": "67d037a752befe01f323769e",
      "sitelinkId": "2191625",
      "tenant": {
        "id": "6797c2402cb24b5fec192b12",
        "firstName": "Russell",
        "lastName": "Jones"
      },
      "location": {
        "id": "6791849148f7fd5b4adff35c",
        "identifier": "LPLANETSETUP",
        "name": "Prime Storage - TESTING"
      },
      "unit": {
        "id": "679ac18058e808bfa19f7511",
        "name": "Unit A1"
      }
    }
  }
}

Summary of Steps

1. Populate Location: Retrieve location details using the provided locationIdentifier.
2. Populate Tenant: Retrieve an existing tenant or create a new one using the provided tenant details.
3. Verify Unit Availability: Ensure the selected unit is available, or assign the next available unit.
4. Populate Unit: Fetch unit details if not already populated.
5. Set Reservation Expiration: Determine the expiration date based on inquiry status.
6. Push to Sitelink: Integrate with Sitelink to create a reservation record.
7. Create Reservation in MongoDB: Save the reservation document with related fields.
8. Error Handling: Throw errors if reservation creation fails.
9. Index in Elasticsearch: Push reservation data to Elasticsearch.
10. Notify via Ably: Send a notification message for the new reservation.
11. Email and Note Scheduling: Schedule emails and notes based on reservation type.
12. Return Reservation: Output the created reservation object.
13. Update Reservation: Populate updated fields, push update to Sitelink, update MongoDB, re-index in Elasticsearch, and send notifications via Ably.
14. Remove Reservation: Delete from MongoDB, remove from Elasticsearch, and notify via Ably.
15. Import Reservations: Fetch locations, set reporting times, process each location and its reservations, and import reservation details from Sitelink.

2️⃣ Updating a Reservation

When updating a reservation, the system performs the following steps:

Step 1: Populate Updated Fields

• Location: If locationIdentifier is provided in the update input, the location is re-fetched using LocationsService.findByIdentifier.
• Tenant: If tenantId is provided, tenant details are re-fetched using TenantsService.findOne.
• Unit: If unitId is provided, unit details are re-fetched using UnitsService.findOne.

Step 2: Push Update to Sitelink

• If Sitelink integration is enabled: The reservation update is sent to Sitelink using SitelinkService.updateReservation. Relevant parameters such as locationIdentifier, sitelinkReservationId, sitelinkTenantId, and sitelinkUnitId are included.

Step 3: Update Reservation in MongoDB

• The reservation is updated using Mongoose’s findByIdAndUpdate with the new input data.
• The updated document is populated with related fields (location, tenant, and unit).

Step 4: Push Update to Elasticsearch

• The updated reservation is re-indexed in Elasticsearch using ElasticsearchService.update.

Step 5: Push Notification via Ably

• A notification about the update is sent using AblySchedulingService.scheduleSendMessage.

Example Mutation for Updating a Reservation

mutation updateReservation(
  $id: ID!
  $updateReservationInput: UpdateReservationInput!
) {
  updateReservation(id: $id, input: $updateReservationInput) {
    id
    reservationStatus
    sitelinkId
    tenant {
      id
      firstName
      lastName
    }
    location {
      id
      identifier
      name
    }
    unit {
      id
      name
    }
  }
}

VARIABLES

{
  "id": "67c65ea6daed933671a4e2a0",
  "updateReservationInput": {
    "unitId": "679189d6d02039930e42591e",
    "neededAt": "2025-04-01T00:00:00.000Z"
  }
}

RESPONSE

{
  "data": {
    "updateReservation": {
      "id": "67c65ea6daed933671a4e2a0",
      "reservationStatus": "ACTIVE",
      "sitelinkId": "2187906",
      "tenant": {
        "id": "6797c2402cb24b5fec192b12",
        "firstName": "Russell",
        "lastName": "Jones"
      },
      "location": {
        "id": "6791849148f7fd5b4adff35c",
        "identifier": "LPLANETSETUP",
        "name": "Prime Storage - TESTING"
      },
      "unit": {
        "id": "679189d6d02039930e42591e",
        "name": "Unit B2"
      }
    }
  }
}

3️⃣ Removing a Reservation

When removing a reservation, the following steps are executed:

Step 1: Delete Reservation from MongoDB

• The reservation is removed using Mongoose’s findByIdAndDelete.

Step 2: Remove Reservation from Elasticsearch

• The reservation is deleted from Elasticsearch using ElasticsearchService.base.delete.

Step 3: Push Notification via Ably

• A notification about the removal is sent using AblySchedulingService.scheduleSendMessage.

Example Mutation for Removing a Reservation

mutation removeReservation($id: ID!) {
  removeReservation(id: $id) {
    id
    reservationStatus
  }
}

VARIABLES

{
  "id": "67c65ea6daed933671a4e2a0"
}

RESPONSE

{
  "data": {
    "removeReservation": {
      "id": "67c65ea6daed933671a4e2a0",
      "reservationStatus": "CANCELLED"
    }
  }
}

4️⃣ Importing Reservations

The system can import reservations from Sitelink. This process includes:

Step 1: Fetch Locations

• All locations are retrieved from MongoDB using LocationsService.findAllMongo.

Step 2: Set Reporting Times

• Reporting times (reportDateStart and reportDateEnd) are determined based on the current day or provided start/end dates.

Step 3: Process Each Location

• For each location (excluding those with a specific annexPrefix):
  • The system fetches all reservations from Sitelink using SitelinkService.getAllReservations.
  • For each reservation:
    • Fetch Reservation Notes:
      Reservation notes are fetched via SitelinkService.getAllReservationNotes.
    • Import Unit:
      The unit is imported using UnitsService.importOne.
    • Import Tenant:
      The tenant is imported using TenantsService.importOne.
    • Import Reservation:
      The reservation is imported (or updated) using createOrUpdateBySitelinkId, merging data from Sitelink with the local database.
• Any errors encountered during this process are logged and captured by Sentry.

Example Flow for Importing Reservations

Note: There isn’t a direct mutation for importing reservations. Instead, the process is triggered by backend jobs that call the import functions (such as importOne and import).

5️⃣ Steps

Create A New Lead

• Create a new lead using the "New Lead" button in the header.
• Fill out the first name, last name, email address and select the unit to rent.
• GraphQL example:

  mutation createRental($input: CreateRentalInput!) {
    createRental(input: $input) {
      tenant {
        id
        firstName
        lastName
        email
        phone
      }
      reservation {
        id
        neededAt
        reservationStatus
        sitelinkId
        quotedRate
      }
    }
  }
  

VARIABLES

{
  "input": {
    "tenant": {
      "company": "",
      "isCompany": false,
      "firstName": "Russell",
      "lastName": "Jones",
      "email": "test+1@test.com",
      "address": "",
      "address2": "",
      "city": "",
      "region": "",
      "postalCode": "",
      "country": "",
      "phone": "(123) 123-1231",
      "mobilePhone": ""
    },
    "neededAt": "2025-03-11T04:00:00.000Z",
    "quotedRate": 75,
    "reservationType": "LEAD",
    "locationIdentifier": "LPLANETSETUP",
    "unitId": "679189d7d02039930c155e7c",
    "concessionId": -999,
    "insuranceId": -999
  }
}

Payload Example:

{
  "data": {
    "createRental": {
      "reservation": {
        "id": "67d037a752befe01f323769e",
        "reservationSource": null,
        "reservationStatus": "ACTIVE",
        "reservationType": null,
        "sitelinkId": "2191625",
        "unit": {
          "id": "679189d7d02039930c155e7c",
          "sitelinkId": "162195"
        }
      },
      "tenant": {
        "id": "6797c2402cb24b5fec192b12",
        "sitelinkId": "2862485"
      }
    }
  }
}

Required Fields for Lead Creation

Field	Required?	Description
locationIdentifier	✅ Yes	The location where the lead is created.
reservationStatus	✅ Yes	Should be ACTIVE for new leads.
reservationType	✅ Yes	Must be set to LEAD.
reservationSource	✅ Yes	Specifies the source of the lead (e.g., WEB).
neededAt	✅ Yes	Timestamp for when the lead is needed.
tenant.firstName	✅ Yes	Lead’s first name.
tenant.lastName	✅ Yes	Lead’s last name.
tenant.email	✅ Yes	Lead’s email address.
unitId	✅ Yes	The ID of the selected unit size.
phone	⛔ No	Optional phone number.

Complete Move-In

• Trigger the Move-In process using the "Move-In" button in the header.

• Fill out the payment details

  Field	Required?	Description
  creditCardNumber	✅ Yes	Valid credit card number (13-19 digits).
  expirationDate	✅ Yes	Expiration Date (MM/YY format).
  creditCardCVV	✅ Yes	CVV (3-4 digits, must be numeric).
  isEnableAutopay	✅ Yes	Enable autopay (boolean).
  address	✅ Yes	Billing Address.
  city	✅ Yes	Billing City.
  region	✅ Yes	Billing State/Province.
  postalCode	✅ Yes	Billing Zip/Postal Code.
  billingName	✅ Yes	Name on credit card.
  insuranceId	✅ Yes	Needed for the final rental payment.
  concessionId	✅ Yes	Required for discount handling.
  paymentAmount	✅ Yes	Amount being charged.

• GraphQL example:

  mutation {
    finalizeRental(
      input: {
        "locationIdentifier": "LPLANETSETUP",
        "tenantId": "6797c2402cb24b5fec192b12",
        "unitId": "679189d7d02039930c155e7c",
        "concessionId": 0,
        "insuranceId": -999,
        "paymentAmount": 75.00,
        "reservationId": "67d037a752befe01f323769e",
        "moveInDate": "2025-03-11T04:00:00.000Z",
        "creditCardType": "Visa",
        "creditCardNumber": "4111 1111 1111 1111",
        "expirationDate": "12/26",
        "creditCardCVV": "123",
        "billingName": "Russell Jones",
        "billingAddress": "123 Main St",
        "billingZipCode": "12345",
        "autoBillType": "CreditCard"
      }
    ) {
      leaseNumber
      ledgerId
      reservation {
        id
        neededAt
      }
    }
  }