# Authentication
Source: https://docs.helloproper.com/api-reference/authentication
Proper uses [API keys](/apikeys) to authenticate requests. You can view and manage your API keys in the [Proper platform](https://app.helloproper.com).
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
```bash Authenticated request theme={null}
curl --request GET \
--url https://api.helloproper.com/bills \
--header 'Authorization: your_secret_key
```
# List bills
Source: https://docs.helloproper.com/api-reference/bills/list
GET /bills
### Request
This request supports pagination.
### Response
The unique identifier for the bill
The identifier for the lease associated with the bill
The creation date and time of the bill in ISO 8601 format
The last modification date and time of the bill in ISO 8601 format
The billing period covered by the bill, in the format "YYYY-MM-DD/YYYY-MM-DD"
The due date for the bill payment in ISO 8601 format
The unique identifier for the bill line item
The amount charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The key or identifier for the product or service billed
The name of the product or service in different languages
The English name of the product or service
The Danish name of the product or service
The Dutch name of the product or service
The German name of the product or service
The VAT details for the bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The accounting period for the bill line item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The subtotal amount for the bill
The currency code for the subtotal (e.g., "DKK")
The subtotal amount
The total amount due for the bill
The currency code for the total (e.g., "DKK")
The total amount due
The total VAT amounts for the bill, split by different VAT rates or categories
The VAT details for the bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The total amount for the VAT category
The currency code for the amount (e.g., "DKK")
The amount
The date in ISO 8601 format when bill was posted
The date in ISO 8601 format when bill was annulled
The number of the invoice corresponding to the bill
The number of the credit note corresponding to the bill
# The bill object
Source: https://docs.helloproper.com/api-reference/bills/object
Bills are statements of amounts owed by a customer, and are either generated one-off, or generated periodically automatically.
Proper will email the bills to your customer and await payment. These emails include the full bill information and all bill line tiems, payment details and an optional PDF invoice.
### Attributes
The unique identifier for the bill
The identifier for the lease associated with the bill
The creation date and time of the bill in ISO 8601 format
The last modification date and time of the bill in ISO 8601 format
The billing period covered by the bill, in the format "YYYY-MM-DD/YYYY-MM-DD"
The due date for the bill payment in ISO 8601 format
The unique identifier for the bill line item
The amount charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The key or identifier for the product or service billed
The name of the product or service in different languages
The English name of the product or service
The Danish name of the product or service
The Dutch name of the product or service
The German name of the product or service
The VAT details for the bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The accounting period for the bill line item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The subtotal amount for the bill
The currency code for the subtotal (e.g., "DKK")
The subtotal amount
The total amount due for the bill
The currency code for the total (e.g., "DKK")
The total amount due
The total VAT amounts for the bill, split by different VAT rates or categories
The VAT details for the bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The total amount for the VAT category
The currency code for the amount (e.g., "DKK")
The amount
The date in ISO 8601 format when bill was posted
The date in ISO 8601 format when bill was annulled
The number of the invoice corresponding to the bill
The number of the credit note corresponding to the bill
# List categories
Source: https://docs.helloproper.com/api-reference/categories/list
GET /categories
### Request
This request supports pagination.
### Response
The unique identifier for the category
The name of the category
The type of the category (e.g., "Properties")
# The category object
Source: https://docs.helloproper.com/api-reference/categories/object
### Attributes
The unique identifier for the category
The name of the category
The type of the category (e.g., "Properties")
# Retrieve a contact
Source: https://docs.helloproper.com/api-reference/contacts/get
GET /contacts/{contactId}
### Params
Contact id
### Response
The unique identifier for the contact
The name of the contact
The email address of the contact
The phone number of the contact.
# List contacts
Source: https://docs.helloproper.com/api-reference/contacts/list
GET /contacts
### Request
This request supports pagination.
### Response
The unique identifier for the contact.
The name of the contact.
The email address of the contact.
The phone number of the contact.
# The contact object
Source: https://docs.helloproper.com/api-reference/contacts/object
### Attributes
The unique identifier for the contact.
The name of the contact.
The email address of the contact.
The phone number of the contact.
# Errors
Source: https://docs.helloproper.com/api-reference/errors
Proper uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided. Codes in the `5xx` range indicate an error with Proper.
| HTTP Status Codes
| |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `200 OK` | Everything worked as expected. The request was unacceptable, often due to missing a required parameter. |
| `400 Bad Request` | The request was unacceptable, often due to missing a required parameter. |
| `401 Unauthorized` | No valid API key provided. |
| `403 Forbidden` | The API key doesn’t have permissions to perform the request. |
| `404 Not Found` | The requested resource doesn’t exist. |
# Introduction
Source: https://docs.helloproper.com/api-reference/introduction
The Proper API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
```bash Base url theme={null}
https://api.helloproper.com
```
# Retrieve a lease
Source: https://docs.helloproper.com/api-reference/leases/get
GET /leases/{leaseId}
### Params
Lease id
### Response
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance details for the lease
The currency code for the balance (e.g., "DKK")
The amount of the balance
The deposit balance details for the lease
The currency code for the deposit balance (e.g., "DKK")
The amount of the deposit balance
The prepaid balance details for the lease
The currency code for the prepaid balance (e.g., "DKK")
The amount of the prepaid balance
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
# List leases
Source: https://docs.helloproper.com/api-reference/leases/list
GET /leases
### Request
This request supports pagination.
### Response
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance details for the lease
The currency code for the balance (e.g., "DKK")
The amount of the balance
The deposit balance details for the lease
The currency code for the deposit balance (e.g., "DKK")
The amount of the deposit balance
The prepaid balance details for the lease
The currency code for the prepaid balance (e.g., "DKK")
The amount of the prepaid balance
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
# List lease transactions
Source: https://docs.helloproper.com/api-reference/leases/list-transactions
GET /leases/{leaseId}/transactions
Returns a paginated list of all transactions for a specific lease.
### Params
The unique identifier of the lease
Maximum number of transactions to return (0-100)
Cursor for pagination. Pass the id of the last transaction from the previous page to get the next page.
### Response
Unique identifier for the transaction
Transaction type: "Payment" or "Charge"
Sequential transaction number within the lease
Transaction amount
ISO 4217 currency code (e.g., "DKK", "EUR")
Numeric amount
VAT/tax information if applicable (nullable)
One of: "Inclusive", "Exclusive", "Exempt", "ReverseCharge"
Tax rate as decimal (e.g., 0.25 for 25%). Null if taxMode is Exempt or ReverseCharge.
Date the transaction was registered (ISO 8601: YYYY-MM-DD)
Date of payment (for payment transactions, nullable)
Date the charge applies to
Payment due date (nullable)
Localized description with translation keys (nullable)
Translation key
Parameters for the translation
Associated product ID (nullable)
Product reference key (nullable)
Multi-language product name (nullable)
English product name
Danish product name
Running balance after this transaction
ISO 4217 currency code (e.g., "DKK", "EUR")
Numeric amount
Whether the transaction has been cancelled
Reason for cancellation (nullable, only if annulled)
Plain text description override (nullable)
Link to associated payment (nullable)
Link to associated bill (nullable)
Link to move-out statement (nullable)
Link to default notice document (nullable)
# The lease object
Source: https://docs.helloproper.com/api-reference/leases/object
### Attributes
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance details for the lease
The currency code for the balance (e.g., "DKK")
The amount of the balance
The deposit balance details for the lease
The currency code for the deposit balance (e.g., "DKK")
The amount of the deposit balance
The prepaid balance details for the lease
The currency code for the prepaid balance (e.g., "DKK")
The amount of the prepaid balance
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
# Logs
Source: https://docs.helloproper.com/api-reference/logs
All events are registered and logged in Proper. You can access the logs under each API key.
# Create one-time bill item
Source: https://docs.helloproper.com/api-reference/one-time-bill-items/create
POST /one-time-bill-items
### Request
The lease for which one-time bill items will be created
The key or identifier for the product or service billed (e.g., "key:rent")
The content of the description that is going to be put on the bill
The amount charged for the one-time bill item
The currency code for the one-time bill item amount (e.g., "DKK")
The amount of the one-time bill item amount (e.g., 100.00)
The quantity of items that is going to be put on the bill
The date in ISO 8601 format that one-time bill item is due
The accounting period for the one-time bill item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The VAT details for the one-time bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
### Response
The unique identifier for the created one-time bill item
The due date in ISO 8601 format of the one-time bill item
# List one-time bill items
Source: https://docs.helloproper.com/api-reference/one-time-bill-items/list
GET /one-time-bill-items
### Request
This request supports pagination.
The lease for which one-time bill items will be returned
### Response
The unique identifier for the one-time bill item
The identifier for the lease associated with the one-time bill item
The creation date and time of the one-time bill item in ISO 8601 format
The last modification date and time of the one-time bill item in ISO 8601 format
The key or identifier for the product or service billed (e.g., "key:rent")
The content of the description that is going to be put on the bill
The amount charged for the one-time bill item
The currency code for the one-time bill item amount (e.g., "DKK")
The amount of one-time bill item (e.g., 100.00)
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The date in ISO 8601 format that one-time bill item is due
The accounting period for the one-time bill item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The VAT details for the one-time bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
# The one-time bill item object
Source: https://docs.helloproper.com/api-reference/one-time-bill-items/object
### Attributes
The unique identifier for the one-time bill item
The identifier for the lease associated with the one-time bill item
The creation date and time of the one-time bill item in ISO 8601 format
The last modification date and time of the one-time bill item in ISO 8601 format
The key or identifier for the product or service billed (e.g., "key:rent")
The content of the description that is going to be put on the bill
The amount charged for the one-time bill item
The currency code for the one-time bill item amount (e.g., "DKK")
The amount of one-time bill item (e.g., 100.00)
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The date in ISO 8601 format that one-time bill item is due
The accounting period for the one-time bill item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The VAT details for the one-time bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
# Pagination
Source: https://docs.helloproper.com/api-reference/pagination
Proper’s API methods use cursor-based pagination through the `startingAfter` parameter. It accepts an existing object ID value and return objects in the specific resource order.
The `startingAfter` parameter returns objects listed after the named object.
### Params
This specifies a limit on the number of objects to return, ranging between 1 and 100.
A cursor to use in pagination. `startingAfter` is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with `obj_propster`, your subsequent call can include `startingAfter=obj_propster` to fetch the next page of the list.
# List payments
Source: https://docs.helloproper.com/api-reference/payments/list
GET /payments
### Request
This request supports pagination.
### Response
The unique identifier for the payment
The date the payment was made
The net amount of the payment
The currency code for the net amount (e.g., "DKK")
The amount of the net amount (e.g., 100.00)
The fees subtracted from the payment
The currency code for the fees amount (e.g., "DKK")
The amount of the fees amount (e.g., 100.00)
The gross amount of the payment
The currency code for the gross amount (e.g., "DKK")
The amount of the gross amount (e.g., 100.00)
The payout that resulted from this payment
The lease identifier that this payment was made to
# The payment object
Source: https://docs.helloproper.com/api-reference/payments/object
Payments are all payments registered on a customer.
Look at Payouts to find the corresponding payments on your bank account.
### Attributes
The unique identifier for the payment
The date the payment was made
The net amount of the payment
The currency code for the net amount (e.g., "DKK")
The amount of the net amount (e.g., 100.00)
The fees subtracted from the payment
The currency code for the fees amount (e.g., "DKK")
The amount of the fees amount (e.g., 100.00)
The gross amount of the payment
The currency code for the gross amount (e.g., "DKK")
The amount of the gross amount (e.g., 100.00)
The payout that resulted from this payment
The lease identifier that this payment was made to
# List payouts
Source: https://docs.helloproper.com/api-reference/payouts/list
GET /payouts
### Request
This request supports pagination.
### Response
The unique identifier for the payout
The reason for the payout. Can be either Payment or Refund
The date the payout was made
The net amount of the payout
The currency code for the net amount (e.g., "DKK")
The amount of the net amount (e.g., 100.00)
The fees subtracted from the payout
The currency code for the fees amount (e.g., "DKK")
The amount of the fees amount (e.g., 100.00)
The gross amount of the payout
The currency code for the gross amount (e.g., "DKK")
The amount of the gross amount (e.g., 100.00)
The bank statement reference for the payout
# The payout object
Source: https://docs.helloproper.com/api-reference/payouts/object
Payouts are the result of payments and a fee to Proper.
To reconcile your bank use the `bankStatement` field.
### Attributes
The unique identifier for the payout
The reason for the payout. Can be either Payment or Refund
The date the payout was made
The net amount of the payout
The currency code for the net amount (e.g., "DKK")
The amount of the net amount (e.g., 100.00)
The fees subtracted from the payout
The currency code for the fees amount (e.g., "DKK")
The amount of the fees amount (e.g., 100.00)
The gross amount of the payout
The currency code for the gross amount (e.g., "DKK")
The amount of the gross amount (e.g., 100.00)
The bank statement reference for the payout
# List pending bills
Source: https://docs.helloproper.com/api-reference/pending-bills/list
GET /pending-bills
### Request
Lease identifier for which pending bills will be retrieved
The period for pending bills, in the format "YYYY-MM-DD/YYYY-MM-DD"
### Response
The due date for the pending bill payment in ISO 8601 format
The key or identifier for the product or service billed
The amount charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The VAT details for the pending bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The accounting period for the pending bill line item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The subtotal amount for the pending bill
The currency code for the subtotal (e.g., "DKK")
The subtotal amount
The total amount due for the pending bill
The currency code for the total (e.g., "DKK")
The total amount due
The total VAT amounts for the pending bill, split by different VAT rates or categories
The VAT details for the pending bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The total amount for the VAT category
The currency code for the amount (e.g., "DKK")
The amount
# The pending bill object
Source: https://docs.helloproper.com/api-reference/pending-bills/object
Pending bills are projections of predicted bills.
### Attributes
The due date for the pending bill payment in ISO 8601 format
The key or identifier for the product or service billed
The amount charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The quantity of items billed
The unit net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The net price charged for the item
The currency code for the amount (e.g., "DKK")
The amount charged
The VAT details for the pending bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The accounting period for the pending bill line item, in the format "YYYY-MM-DD/YYYY-MM-DD"
The subtotal amount for the pending bill
The currency code for the subtotal (e.g., "DKK")
The subtotal amount
The total amount due for the pending bill
The currency code for the total (e.g., "DKK")
The total amount due
The total VAT amounts for the pending bill, split by different VAT rates or categories
The VAT details for the pending bill line item
The tax mode for the VAT (e.g., "Exempt")
The tax rate for the VAT (e.g., 0.25)
The total amount for the VAT category
The currency code for the amount (e.g., "DKK")
The amount
# List products
Source: https://docs.helloproper.com/api-reference/products/list
GET /products
### Request
This request supports pagination.
### Response
The key or identifier for the product
The unique identifier for the product (if applicable)
The name of the product in different languages
The English name of the product
The Danish name of the product
The Dutch name of the product
The German name of the product
Indicator whether the product is archived
Indicator whether the product is a custom product
The position or order of the product in a list
Indicator whether the product is a default product
# The products object
Source: https://docs.helloproper.com/api-reference/products/object
### Attributes
The key or identifier for the product
The unique identifier for the product (if applicable)
The name of the product in different languages
The English name of the product
The Danish name of the product
The Dutch name of the product
The German name of the product
Indicator whether the product is archived
Indicator whether the product is a custom product
The position or order of the product in a list
Indicator whether the product is a default product
# Create recurring bill item
Source: https://docs.helloproper.com/api-reference/recurring-bill-items/create
POST /recurring-bill-items
### Request
The lease for which recurring bill items will be created
The key or identifier for the product or service billed (e.g., "key:rent")
The content of the description that is going to be put on the bill
The amount charged for the recurring bill item
The currency code for the recurring bill item amount (e.g., "DKK")
The amount of the recurring bill item amount (e.g., 100.00)
The quantity of items that is going to be put on the bill
The VAT details for the recurring bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
The rule used to calculate the due date
The day of the period when the due date is calculated (e.g., 1 for the first day after period starts, -1 for the last day before period starts)
Time unit based on which the billing cycle is calculated ("Month")
The number of time units in the billing cycle (e.g., 1 month, 3 months)
Index of what day within the billing period the cycle starts (usually 1 for the first day of the period)
First due date for the recurring bill item in ISO 8601 format
The amount charged for the first billing period recurring bill item
The currency code for the first billing period recurring bill item amount (e.g., "DKK")
The amount of the first billing period recurring bill item amount (e.g., 100.00)
The due date in ISO 8601 format of the first billing period bill item
The accounting period for the first billing period bill item, in the format "YYYY-MM-DD/YYYY-MM-DD"
Discount that is going to be applied to the recurring bill item
The amount that is going to be subtracted from the recurring bill item amount
Either this or "percentage" is required
The currency code for the amount subtracted from the recurring bill item amount (e.g., "DKK")
The amount subtracted from the recurring bill item amount (e.g., 100.00)
The percentage of the recurring bill item amount that is going to be subtracted (e.g., 0.10)
Either this or "amount" is required
The content of the discount description that is going to be put on the bill
The date in ISO 8601 format on which discount ends
### Response
The unique identifier for the created recurring bill item
The first due date in ISO 8601 format of the recurring bill item
# List recurring bill items
Source: https://docs.helloproper.com/api-reference/recurring-bill-items/list
GET /recurring-bill-items
### Request
This request supports pagination.
The lease for which recurring bill items will be returned
### Response
The unique identifier for the recurring bill item
The identifier for the owner associated with the recurring bill item
The identifier for the lease associated with the recurring bill item
The creation date and time of the recurring bill item in ISO 8601 format
The last modification date and time of the recurring bill item in ISO 8601 format
The key or identifier for the product or service billed (e.g., "key:rent")
First due date for the recurring bill item in ISO 8601 format
The date in ISO 8601 format on which recurring bill item is stopped from being billed
The date in ISO 8601 format on which recurring bill item ends billing
Time unit based on which the billing cycle is calculated ("Month")
The number of time units in the billing cycle (e.g., 1 month, 3 months)
Index of a month when the billing cycle starts (e.g., 1 for January)
The unique identifier for the amount record
The amount charged for the recurring bill item
The currency code for the recurring bill item amount (e.g., "DKK")
The amount of the recurring bill item amount (e.g., 100.00)
The date in ISO 8601 format from which the amount is valid
The unique identifier for the VAT Record
The VAT details for the recurring bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
The date in ISO 8601 format from which the VAT is valid
The unique identifier for the description record
The content of the description that is going to be put on the bill
The date in ISO 8601 format from which the description is valid
The unique identifier for the quantity record
The quantity of items that is going to be put on the bill
The date in ISO 8601 format from which the quantity is valid
# The recurring bill item object
Source: https://docs.helloproper.com/api-reference/recurring-bill-items/object
### Attributes
The unique identifier for the recurring bill item
The identifier for the owner associated with the recurring bill item
The identifier for the lease associated with the recurring bill item
The creation date and time of the recurring bill item in ISO 8601 format
The last modification date and time of the recurring bill item in ISO 8601 format
The key or identifier for the product or service billed (e.g., "key:rent")
First due date for the recurring bill item in ISO 8601 format
The date in ISO 8601 format on which recurring bill item is stopped from being billed
The date in ISO 8601 format on which recurring bill item ends billing
Time unit based on which the billing cycle is calculated ("Month")
The number of time units in the billing cycle (e.g., 1 month, 3 months)
Index of a month when the billing cycle starts (e.g., 1 for January)
The unique identifier for the amount record
The amount charged for the recurring bill item
The currency code for the recurring bill item amount (e.g., "DKK")
The amount of the recurring bill item amount (e.g., 100.00)
The date in ISO 8601 format from which the amount is valid
The unique identifier for the VAT Record
The VAT details for the recurring bill item
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
The date in ISO 8601 format from which the VAT is valid
The unique identifier for the description record
The content of the description that is going to be put on the bill
The date in ISO 8601 format from which the description is valid
The unique identifier for the quantity record
The quantity of items that is going to be put on the bill
The date in ISO 8601 format from which the quantity is valid
# List rent adjustments
Source: https://docs.helloproper.com/api-reference/rent-adjustment/list
GET /rent-adjustment-plans
### Request
This request supports pagination.
### Response
The unique identifier for the rent adjustment plan
The identifier for the lease associated with the rent adjustment plan
The creation date and time of the rent adjustment plan in ISO 8601 format
The last modification date and time of the rent adjustment plan in ISO 8601 format
The reference to the adjustee in the rent adjustment plan
The type of the balance charge adjusted by the rent adjustment (if applicable)
The next adjustment date in ISO 8601 format (if applicable)
The rent adjustment cancellation date in ISO 8601 format (if applicable)
The rent adjustment end date in ISO 8601 format (if applicable)
The rent adjustment cancellation date or end date, in ISO 8601 format (if applicable)
Indicator whether the plan adjusts a recurring bill item
Indicator whether the plan adjusts a balance
The VAT setting for the rent adjustment
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
The unique identifier for the rent adjustment rule
The type of adjustment (e.g., "Index")
The month when adjustment occurs
The first year of the adjustment rule
The last year of the rent adjustment rule
The month of the index used for the adjustment (if applicable)
The minimum percentage used for the adjustment (if applicable)
The maximum percentage used for the adjustment (if applicable)
The increments used for the adjustment year by year
The year when the increment occurs
The amount used for the increment
The currency code for the increment amount (e.g., "DKK")
The amount of the increment amount (e.g., 100.00)
The percentage used for the increment
The recurrence of the increment (e.g., "Recurring", "OneTime")
The unique identifier for the adjustment
The date when the adjustment was made in ISO 8601 format
The year the adjustment is applicable
The from yearly amount used for the rent adjustment (if applicable)
The currency code for the from yearly amount (e.g., "DKK")
The amount of the from yearly amount (e.g., 100.00)
The to yearly amount used for the rent adjustment (if applicable)
The currency code for the to yearly amount (e.g., "DKK")
The amount of the to yearly amount (e.g., 100.00)
The yearly amount change of the rent adjustment (if applicable)
The currency code for the yearly amount change (e.g., "DKK")
The amount of the yearly amount change (e.g., 100.00)
The period amount change of the rent adjustment (if applicable)
The currency code for the period amount change (e.g., "DKK")
The amount of the period amount change (e.g., 100.00)
The from period amount of the rent adjustment (if applicable)
The currency code for the from period amount (e.g., "DKK")
The amount of the from period amount (e.g., 100.00)
The to period amount of the rent adjustment (if applicable)
The currency code for the to period amount (e.g., "DKK")
The amount of the to period amount (e.g., 100.00)
The from balance amount of the rent adjustment (if applicable)
The currency code for the from balance amount (e.g., "DKK")
The amount of the from balance amount (e.g., 100.00)
The to balance amount of the rent adjustment (if applicable)
The currency code for the to balance amount (e.g., "DKK")
The amount of the to balance amount (e.g., 100.00)
The balance amount change of the rent adjustment (if applicable)
The currency code for the balance amount change (e.g., "DKK")
The amount of the balance amount change (e.g., 100.00)
The unique identifier for the corresponding rent adjustment rule
The calculated adjustment percentage (if applicable)
The from index used to calculate the percentage (if applicable)
The to index used to calculate the percentage (if applicable)
The from year and month used to calculate the percentage (if applicable)
The to year and month used to calculate the percentage (if applicable)
The from yearly amount used for the rent adjustment rule (if applicable)
The currency code for the from yearly amount (e.g., "DKK")
The amount of the from yearly amount (e.g., 100.00)
The to yearly amount used for the rent adjustment rule (if applicable)
The currency code for the to yearly amount (e.g., "DKK")
The amount of the to yearly amount (e.g., 100.00)
The yearly amount change of the rent adjustment rule (if applicable)
The currency code for the yearly amount change (e.g., "DKK")
The amount of the yearly amount change (e.g., 100.00)
The period amount change of the rent adjustment rule (if applicable)
The currency code for the period amount change (e.g., "DKK")
The amount of the period amount change (e.g., 100.00)
The from period amount of the rent adjustment rule (if applicable)
The currency code for the from period amount (e.g., "DKK")
The amount of the from period amount (e.g., 100.00)
The to period amount of the rent adjustment rule (if applicable)
The currency code for the to period amount (e.g., "DKK")
The amount of the to period amount (e.g., 100.00)
The from balance amount of the rent adjustment rule (if applicable)
The currency code for the from balance amount (e.g., "DKK")
The amount of the from balance amount (e.g., 100.00)
The to balance amount of the rent adjustment rule (if applicable)
The currency code for the to balance amount (e.g., "DKK")
The amount of the to balance amount (e.g., 100.00)
The balance amount change of the rent adjustment rule (if applicable)
The currency code for the balance amount change (e.g., "DKK")
The amount of the balance amount change (e.g., 100.00)
The minimum percentage used for the adjustment rule (if applicable)
The maximum percentage used for the adjustment rule (if applicable)
# The rent adjustment plan object
Source: https://docs.helloproper.com/api-reference/rent-adjustment/object
### Attributes
The unique identifier for the rent adjustment plan
The identifier for the lease associated with the rent adjustment plan
The creation date and time of the rent adjustment plan in ISO 8601 format
The last modification date and time of the rent adjustment plan in ISO 8601 format
The reference to the adjustee in the rent adjustment plan
The type of the balance charge adjusted by the rent adjustment (if applicable)
The next adjustment date in ISO 8601 format (if applicable)
The rent adjustment cancellation date in ISO 8601 format (if applicable)
The rent adjustment end date in ISO 8601 format (if applicable)
The rent adjustment cancellation date or end date, in ISO 8601 format (if applicable)
Indicator whether the plan adjusts a recurring bill item
Indicator whether the plan adjusts a balance
The VAT setting for the rent adjustment
The tax mode for the VAT (e.g., "Exempt", "Exclusive")
The tax rate for the VAT (e.g., 0.25)
The unique identifier for the rent adjustment rule
The type of adjustment (e.g., "Index")
The month when adjustment occurs
The first year of the adjustment rule
The last year of the rent adjustment rule
The month of the index used for the adjustment (if applicable)
The minimum percentage used for the adjustment (if applicable)
The maximum percentage used for the adjustment (if applicable)
The increments used for the adjustment year by year
The year when the increment occurs
The amount used for the increment
The currency code for the increment amount (e.g., "DKK")
The amount of the increment amount (e.g., 100.00)
The percentage used for the increment
The recurrence of the increment (e.g., "Recurring", "OneTime")
The unique identifier for the adjustment
The date when the adjustment was made in ISO 8601 format
The year the adjustment is applicable
The from yearly amount used for the rent adjustment (if applicable)
The currency code for the from yearly amount (e.g., "DKK")
The amount of the from yearly amount (e.g., 100.00)
The to yearly amount used for the rent adjustment (if applicable)
The currency code for the to yearly amount (e.g., "DKK")
The amount of the to yearly amount (e.g., 100.00)
The yearly amount change of the rent adjustment (if applicable)
The currency code for the yearly amount change (e.g., "DKK")
The amount of the yearly amount change (e.g., 100.00)
The period amount change of the rent adjustment (if applicable)
The currency code for the period amount change (e.g., "DKK")
The amount of the period amount change (e.g., 100.00)
The from period amount of the rent adjustment (if applicable)
The currency code for the from period amount (e.g., "DKK")
The amount of the from period amount (e.g., 100.00)
The to period amount of the rent adjustment (if applicable)
The currency code for the to period amount (e.g., "DKK")
The amount of the to period amount (e.g., 100.00)
The from balance amount of the rent adjustment (if applicable)
The currency code for the from balance amount (e.g., "DKK")
The amount of the from balance amount (e.g., 100.00)
The to balance amount of the rent adjustment (if applicable)
The currency code for the to balance amount (e.g., "DKK")
The amount of the to balance amount (e.g., 100.00)
The balance amount change of the rent adjustment (if applicable)
The currency code for the balance amount change (e.g., "DKK")
The amount of the balance amount change (e.g., 100.00)
The unique identifier for the corresponding rent adjustment rule
The calculated adjustment percentage (if applicable)
The from index used to calculate the percentage (if applicable)
The to index used to calculate the percentage (if applicable)
The from year and month used to calculate the percentage (if applicable)
The to year and month used to calculate the percentage (if applicable)
The from yearly amount used for the rent adjustment rule (if applicable)
The currency code for the from yearly amount (e.g., "DKK")
The amount of the from yearly amount (e.g., 100.00)
The to yearly amount used for the rent adjustment rule (if applicable)
The currency code for the to yearly amount (e.g., "DKK")
The amount of the to yearly amount (e.g., 100.00)
The yearly amount change of the rent adjustment rule (if applicable)
The currency code for the yearly amount change (e.g., "DKK")
The amount of the yearly amount change (e.g., 100.00)
The period amount change of the rent adjustment rule (if applicable)
The currency code for the period amount change (e.g., "DKK")
The amount of the period amount change (e.g., 100.00)
The from period amount of the rent adjustment rule (if applicable)
The currency code for the from period amount (e.g., "DKK")
The amount of the from period amount (e.g., 100.00)
The to period amount of the rent adjustment rule (if applicable)
The currency code for the to period amount (e.g., "DKK")
The amount of the to period amount (e.g., 100.00)
The from balance amount of the rent adjustment rule (if applicable)
The currency code for the from balance amount (e.g., "DKK")
The amount of the from balance amount (e.g., 100.00)
The to balance amount of the rent adjustment rule (if applicable)
The currency code for the to balance amount (e.g., "DKK")
The amount of the to balance amount (e.g., 100.00)
The balance amount change of the rent adjustment rule (if applicable)
The currency code for the balance amount change (e.g., "DKK")
The amount of the balance amount change (e.g., 100.00)
The minimum percentage used for the adjustment rule (if applicable)
The maximum percentage used for the adjustment rule (if applicable)
# Creates a tenancy
Source: https://docs.helloproper.com/api-reference/tenancies/create
POST /tenancies
### Params
The purpose of the lease (e.g., "key:residential")
The address details of the tenancy
The name of the street
The number of the property on the street
The postal code for the address
The city of the address
The country code of the address
The floor of the address if applicable
The door of the address if applicable
The subdivision of the address if applicable
The c/o for the address if applicable
### Response
The unique identifier for the created tenancy
The unique identifier for the draft lease created for the tenancy
# Retrieve a tenancy
Source: https://docs.helloproper.com/api-reference/tenancies/get
GET /tenancies/{tenancyId}
### Params
Tenancy id
### Response
The unique identifier for the tenancy
The address details of the tenancy
The full street name and number
The name of the street
The number of the property on the street
The floor of the address if applicable
The door of the address if applicable
The subdivision of the address if applicable
The postal code for the address
The city of the address
The country code of the address
Categories mapped to the corresponding groups
The details of the Current Lease Object for the tenancy
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of balance amount (e.g., 100.00)
The deposit balance for the lease
The currency code for the deposit balance amount (e.g., "DKK")
The amount of the prepaid balance amount (e.g., 100.00)
The prepaid balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of prepaid balance amount (e.g., 100.00)
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
The identifiers for all leases associated with the tenancy
The type of the unit (e.g., "PARKING")
The description of unit type, if unit type is "OTHER"
The type of the room (e.g., "ROOM")
The count of the room type
The total area of the tenancy
The value of the total area
The unit of measurement for the area (e.g., "m²")
The business area of the tenancy
The value of the business area
The unit of measurement for the area (e.g., "m²")
The date-time in ISO 8601 format of archiving the tenancy
# List tenancies
Source: https://docs.helloproper.com/api-reference/tenancies/list
GET /tenancies
### Request
This request supports pagination.
### Response
The unique identifier for the tenancy
The address details of the tenancy
The full street name and number
The name of the street
The number of the property on the street
The floor of the address if applicable
The door of the address if applicable
The subdivision of the address if applicable
The postal code for the address
The city of the address
The country code of the address
Categories mapped to the corresponding groups
The details of the Current Lease Object for the tenancy
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of balance amount (e.g., 100.00)
The deposit balance for the lease
The currency code for the deposit balance amount (e.g., "DKK")
The amount of the prepaid balance amount (e.g., 100.00)
The prepaid balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of prepaid balance amount (e.g., 100.00)
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
The identifiers for all leases associated with the tenancy
The type of the unit (e.g., "PARKING")
The description of unit type, if unit type is "OTHER"
The type of the room (e.g., "ROOM")
The count of the room type
The total area of the tenancy
The value of the total area
The unit of measurement for the area (e.g., "m²")
The business area of the tenancy
The value of the business area
The unit of measurement for the area (e.g., "m²")
The date-time in ISO 8601 format of archiving the tenancy
# The tenancy object
Source: https://docs.helloproper.com/api-reference/tenancies/object
### Attributes
The unique identifier for the tenancy
The address details of the tenancy
The full street name and number
The name of the street
The number of the property on the street
The floor of the address if applicable
The door of the address if applicable
The subdivision of the address if applicable
The postal code for the address
The city of the address
The country code of the address
Categories mapped to the corresponding groups
The details of the Current Lease Object for the tenancy
The unique identifier for the lease
The identifier for the tenancy associated with the lease
The operational state of the lease (e.g., "Draft")
The state of the contract period (e.g., "Active")
The name of the primary tenant contact
The identifiers for the tenants
The identifiers for the associated contacts
The identifier for the primary tenant
The identifier for the billing contact
The balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of balance amount (e.g., 100.00)
The deposit balance for the lease
The currency code for the deposit balance amount (e.g., "DKK")
The amount of the prepaid balance amount (e.g., 100.00)
The prepaid balance for the lease
The currency code for the balance amount (e.g., "DKK")
The amount of prepaid balance amount (e.g., 100.00)
The start date of the contract in ISO 8601 format
The end date of the contract in ISO 8601 format
The purpose of the lease (e.g., "key:residential")
The monthly rent level details for the lease
The currency code for the monthly rent level (e.g., "DKK")
The amount of the monthly rent level
The date-time in ISO 8601 format of archiving the lease
The identifiers for all leases associated with the tenancy
The type of the unit (e.g., "PARKING")
The description of unit type, if unit type is "OTHER"
The type of the room (e.g., "ROOM")
The count of the room type
The total area of the tenancy
The value of the total area
The unit of measurement for the area (e.g., "m²")
The business area of the tenancy
The value of the business area
The unit of measurement for the area (e.g., "m²")
The date-time in ISO 8601 format of archiving the tenancy
# The transaction object
Source: https://docs.helloproper.com/api-reference/transactions/object
### Attributes
Unique identifier for the transaction
Transaction type: "Payment" or "Charge"
Sequential transaction number within the lease
Transaction amount
ISO 4217 currency code (e.g., "DKK", "EUR")
Numeric amount
VAT/tax information if applicable (nullable)
One of: "Inclusive", "Exclusive", "Exempt", "ReverseCharge"
Tax rate as decimal (e.g., 0.25 for 25%). Null if taxMode is Exempt or ReverseCharge.
Date the transaction was registered (ISO 8601: YYYY-MM-DD)
Date of payment (for payment transactions, nullable)
Date the charge applies to
Payment due date (nullable)
Localized description with translation keys (nullable)
Translation key
Parameters for the translation
Associated product ID (nullable)
Product reference key (nullable)
Multi-language product name (nullable)
English product name
Danish product name
Running balance after this transaction
ISO 4217 currency code (e.g., "DKK", "EUR")
Numeric amount
Whether the transaction has been cancelled
Reason for cancellation (nullable, only if annulled)
Plain text description override (nullable)
Link to associated payment (nullable)
Link to associated bill (nullable)
Link to move-out statement (nullable)
Link to default notice document (nullable)
# Versioning
Source: https://docs.helloproper.com/api-reference/versioning
You are currently viewing the latest version of Proper API.
# API keys
Source: https://docs.helloproper.com/apikeys
Learn how to get API access to your Proper account.
## Create an API key
Proper authenticates your API requests using your account’s API keys. If a request doesn’t include a valid key,
Proper returns an invalid request error. If a request includes a deleted key, Proper returns an authentication error.
We recommend creating [restricted API keys](#restricted-api-keys) and limit data acess to individual resources.
Make sure you are viewing the entity you want to generate an API key for.
Under Settings you find API keys. Here are the existing keys listed, view request logs and make new keys.
Make sure to give your API key a meaningful name and the necessary permissions. You can always update the permissions later.
## Multiple legal entities
Proper generate a unique ID for each legal entity – we call this an owner. You can think of an owner as a separate account.
When requesting the API you need an API key per owner that you want to access.
Follow the steps above to optain an API Key for each of your owners.
## Restricted API keys
For optimal security, generate restricted API keys with precise access controls. For instance, when syncing with your accounting system, use a key that exclusively permits write operations, preventing unauthorized modifications or access to unrelated data.
# Introduction
Source: https://docs.helloproper.com/introduction
Explore our guides and examples to integrate Proper.
## Getting access
You can begin as soon as you have a Proper account. [Sign up on our website](https://helloproper.com), or [login to Proper's platform](https://app.helloproper.com).
Read how to authenticate and make API requests using secure and restricted keys.
## Get started with Proper API
Connect your own applications to your Proper account for a personalised customer experience.
Dig into our API reference. Everything you need to get started using Proper API.
Listen for events on your Proper account so your integration can automatically trigger reactions.
# Webhooks (coming soon)
Source: https://docs.helloproper.com/webhooks
Listen for events on your Proper account so your integration can automatically trigger reactions.
## Why use webhooks
Integrating Proper into your applications offers the valuable capability to instantly respond to events occurring within your Proper account. This real-time responsiveness is enabled through webhook events.
To tap into these events, begin by setting up webhook endpoints in your system. Once registered, Proper seamlessly streams live event data directly to your application's webhook endpoint. This happens through secure HTTPS connections, with Proper dispatching JSON payloads containing an event object.
Webhook events are incredibly useful for tracking asynchronous activities. For instance, they keep you updated on key events like payment reconciliations, bill creations, lease terminations, or rent adjustments. This feature ensures your backend systems are always in sync with the latest developments in your Proper account.
### Webhook events
By registering webhook endpoints in your Proper account, you enable Proper to automatically send an event as part of POST requests to the registered webhook endpoint hosted by your application. After your webhook endpoint receives the event, your application can run backend actions. For example, it could trigger your ERP system's API to log a customer payment upon receiving a `payment_received` event.
#### Example event object
```bash theme={null}
{
example: "coming soon"
}
```
#### Events
Coming soon.