Lease - Use Examples

Last updated
Save as PDF

REST API

Overview

The Lease REST API lets external systems push lease-related data into Archibus over HTTP. All endpoints accept JSON, return JSON, and use a bulk upsert model — one call can carry many records at once. Each record succeeds or fails independently; a bad record does not block the rest of the batch.

Tips

Batch size — Up to 100 records per request is the recommended limit for reliable performance.
Source tracking — Populates source_ref with the originating system's record ID so records can be traced back to the source.
Idempotency — Sending the same record twice is safe; the second call updates the existing row with the same values.
Date fields — Always supply dates as strings in ISO 8601 format (2025-06-30 or 2025-06-30T00:00:00Z). Other formats are rejected.
Case sensitivity — Enum values are case-sensitive. TENANT is valid; tenant and Tenant are not (for the lease endpoint).

Base URL

https://<host>/archibus/rest

Replace <host> with your Archibus server hostname.

Endpoints

This lists the endpoints that can be used.


Endpoint	What it upserts
`POST /leases`	Lease records (`ls` table)
`POST /buildings`	Building records (`bl` table)
`POST /leases/{lsId}/contacts`	Contacts linked to a lease
`POST /leases/{lsId}/clauses`	Lease clause records
`POST /leases/{lsId}/options`	Lease option records
`POST /leases/{lsId}/payment-schedules`	Payment schedule records
`POST /leases/{lsId}/amendments`	Lease amendment records

Upsert logic: If a record with the same primary key already exists, it is updated; otherwise it is created.

Request Format

Send a JSON array of field-value objects.

A single object (not wrapped in an array) is also accepted.

POST /archibus/rest/leases
Content-Type: application/json

[
  {
    "ls_id": "LS-001",
    "landlord_tenant": "TENANT",
    "lease_sublease": "LEASE",
    "source_status": "ACTIVE",
    "source_ref": "ERP-12345"
  },
  {
    "ls_id": "LS-002",
    "landlord_tenant": "LANDLORD",
    "lease_sublease": "SUBLEASE"
  }
]

The request body must not be an empty array. Send at least one record.

Allowed values for validated fields

Fields marked required must be present in every record and fields marked optional are validated only when supplied.

Lease (`POST /leases`)


Field	Required?	Allowed values
`landlord_tenant`	Required	LANDLORD, TENANT
`lease_sublease`	Required	LEASE, SUBLEASE
`source_status`	Optional	NA, ACTIVE, DELETED, PROCESSING

Building (`POST /buildings`)


Field	Required?	Allowed values
`status`	Required	`Active`, `Inactive`

Contact (`POST /leases/{lsId}/contacts`)


Field	Required?	Allowed values
`status`	Required	`Active`, `Inactive`
`contact_type`	Optional	`Tenant`, `Landlord`, `Mgmt Co`, `Guarantor`

Clauses, options, payment schedules, and amendments have no enum-constrained fields and accept any valid field values.

Response Format

{
  "created": 1,
  "updated": 1,
  "failed": 1,
  "records": [
    { "id": "LS-001", "status": "CREATED" },
    { "id": "LS-002", "status": "UPDATED" },
    { "id": "LS-003", "status": "FAILED", "error": "Missing required field 'landlord_tenant'..." }
  ]
}


Field	Description
`created`	Number of records inserted
`updated`	Number of records updated
`failed`	Number of records that could not be processed
`records[].status`	CREATED, UPDATED, or FAILED per record
`records[].error`	Human-readable reason (only present when status is FAILED)

Common Errors

This lists the common errors that may be encountered.


HTTP status	When it happens	What to do
400 Bad Request	Missing required field, invalid enum value, or empty array body.	Check the `error` field in the failed record(s); correct the value and retry.
400 Bad Request	Invalid date format.	Use ISO 8601: `yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss'Z'`
404 Not Found	`{lsId}` path parameter does not match any lease.	Verify the lease exists before posting child records.
415 Unsupported Media Type	Missing or wrong `Content-Type` header.	Always send `Content-Type: application/json`
500 Internal Server Error	Unexpected server-side failure.	Contact your Archibus administrator with the request payload and timestamp.