Find Leases For Tenant
This endpoint finds leases for a specific tenant based on provided parameters.
The endpoint will automatically match the tenant information provided with an existing tenant within the system.
At least one of the following tenant identifiers need to be provided:
- Internal tenant identifier (
identifier) - External tenant identifier (
external_ref) and the group id the tenant belongs to (group) - The email address of the tenant (
email_address) - The phone number of the tenant (
phone_number)
If no tenant match is retrieved, an empty set of leases will be returned.
Active leases have an end date in the future and a start date in the past relative to the current date.
All date fields included in the body parameters need to be specified as ISO8601-formatted date strings.
Date fields should follow a “YYYY-MM-DD” format.
If finding tenants via their external referance, you must provide the group the tenant belongs to.
The group can be specified via either the group_id or group_external_ref attribute.
Do not provide both, as this will result in the request failing.
Example use cases
This endpoint allows you to find leases for a specific tenant.
You can retrieve all leases for a tenant given their internal id or external reference and group id.
You can retrieve all leases for a tenant given their phone number or email address.
Header
The authentication token for your request
Body
The identifier for the tenant to retrieve leases for.
The external identifier for the tenant to retrieve leases for.
The email address for the tenant to retrieve leases for.
The phone number for the tenant to retrieve leases for.
Determines whether only active leases are retrieved for the provided tenant.
The id of the group the tenant belongs to.
This attribute or the group_external_ref one is needed if using the external_ref for the tenant.
The external reference of the group the tenant belongs to.
This attribute or the group_id one is needed if using the external_ref for the tenant.
The API returns a maximum of 100 records per call.
You can use this parameter to load the next set of records by passing in the value returned in the response, under last_id.
Response
The last id in the set of results returned for this API call.
You can use this value in the after-id parameter to load the next set of results.
If there are no more results to load, this value will be -1.
A list of the leases that have been retrieved.
Errors
Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.
Status Code - 400
{
"error": {
"type": "missing_authorization",
"message": "Your request does not include an 'Authorization' header with a bearer token for your account."
}
}
Status Code - 401
{
"error": {
"type": "expired_token",
"message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
}
}
Status Code - 401
{
"error": {
"type": "invalid_authorization",
"message": "The bearer token you have provided in the 'Authorization' header is invalid."
}
}
Status Code - 400
Returned if none of the tenant parameters are provided in the request body
{
"error": {
"type": "no_tenant_information",
"message": "You need to provide at least one of identifier, external_ref AND group, email_address, or phone_number in the request body."
}
}
Status Code - 400
Returned if both of the group_id and group_external_ref attributes are provided
{
"error": {
"type": "both_group_identifiers_provided",
"message": "You have provided both the group id and group external reference for the find leases for tenant operation. Please only provide one of the two."
}
}
Status Code - 400
Returned if no group_id or group_external_ref is provdided when identifying a tenant via an external_ref
{
"error": {
"type": "both_group_identifiers_provided",
"message": "You have not a group id or group external reference when identifying a tenant via their external reference. Please provide one of the two."
}
}