NAV
code

Introduction

# Live API url
https://api.rentshare.com/
# Staging API url
https://staging-api.rentshare.com/
# Staging plugin url
https://staging.rentshare.com/

The RentShare integration API is based on a RESTful api design with some nuances. You can explore the API implementation specifics in the General section or go right to the fun and Get started!

Get started

Get units, leases, invoices

import requests

api_key = 'api_key_6fsMi3GDxXg1XXSluNx1sLEd'
units   = requests.get('https://api.rentshare.com/units',
  auth=(api_key,'')).json()

Calling GET /units will return a list of all units and their leases, tenants, invoices, and invoice items.

The units list returned includes all subobjects. Below is the object hierarchy:

  [
    {
      address: { ... },
      leases: [
        {
          tenants: [ { ... }, { ... } ],
          invoices: [
            {
              payers: [
                {
                  payments: [ { ... }, { ... } ]
                },
                { ... },
              ],
              items: [
                {
                  assignments: [ { ... }, { ... } ]
                },
                { ... },
              ]
            },
            { ... },
          ]
        },
        { ... },
    },
    { ... },
  ]

Update a lease

for unit in units:
    for lease in unit['leases']:
        lease['due_day'] = 1

units = requests.put('https://api.rentshare.com/units',
  auth=(api_key,''), json=units).json()

You can pass back the same object with any updates to the hierarchy in and PUT call.


Adding a lease

units[0]['leases'].append({
  'due_day': 1,
  'start_date': '2015-10-1',
  'rent_amount': 1000.00,
  'tenants': [{
    'email': 'john.doe@gmail.com',
    'first_name': 'John',
    'last_name': 'Doe',
  }]
})

units = requests.put('https://api.rentshare.com/units',
  auth=(api_key,''), json=units).json()

You can pass back the same object with any new objects to the hierarchy with a PUT call. This will create any new objects found in the hierarchy.


Delete lease

del units[0]['leases'][-1]

units = requests.put('https://api.rentshare.com/units',
  auth=(api_key,''), json=units).json()

You can pass back the same object with any objects removed from hierarchy with a PUT call. This will delete any missing objects from the resulting hierarchy.


General

The HTTP verbs used are GET to select objects, POST to create objects, PUT to update objects, and DELETE to delete objects. Objects can be manipulated in single, bulk, or query modes.

Authentication

# Using curl, you can pass the api key with each request
curl -s "https://api.rentshare.com/units" \
-u api_key_6fsMi3GDxXg1XXSluNx1sLEd:

Make sure to append your api key with : when using curl.

RentShare uses API keys to allow access to the API. Your API keys can be found on your settings page under Extras.

RentShare expects for the API key to be included in all API requests to the server using HTTP Basic Auth.

Methods

Select

Select method uses the HTTP verb GET to retrieve objects and works in two modes: single and query.

Single mode

GET https://api.rentshare.com/leases/{id1}[,{id2},...]

No request body

Query mode (See the query language)

GET https://api.rentshare.com/leases/?field=value

No request body

Create

Create method uses the HTTP verb POST to create objects and works in two modes: single and bulk.

Single mode

POST https://api.rentshare.com/leases/

Request body:

{ ... } single json object

Bulk mode

POST https://api.rentshare.com/leases/

Request body:

[ { ... }, { ... }, { ... } ] Array with multiple objects

Update

Update method uses the HTTP verb PUT to update objects and works in three modes: single, query, and bulk.

Single mode

PUT https://api.rentshare.com/leases/{id1}[,{id2},...]

{ ... } single json object

Query mode (See the query language)

PUT https://api.rentshare.com/leases/?field=value

{ ... } single json object with fields to update

Bulk mode

PUT https://api.rentshare.com/leases/

[ { id: {id1}, ... }, { id: {id2}, ... } ] Array with multiple objects

Delete

Delete method uses the HTTP verb DELETE to delete objects and works in two modes: single, query, and bulk.

Single mode

PUT https://api.rentshare.com/leases/{id1}[,{id2},...]

No request body

Query mode (See the query language)

PUT https://api.rentshare.com/leases/?field=value

No request body

Bulk mode

PUT https://api.rentshare.com/leases/

[ { id: {id1}, ... }, { id: {id2}, ... } ] Array with multiple objects

Embedded objects

Resource objects can have other related resource objects embedded within their object hierarchy. This means that a top or higher level resource will return the main resource object along with the underlying embedded object hierarchy.

response = requests.get( base_url + '/leases/393',
  auth=( api_key, '' ) )
lease = response.json()
print lease
{
  "id": 393,
  "tenants": [
    {
      "id": 77,
      "lease_id": 393
    }
  ]
}

For example, the /leases endpoint has a list of associated /tenants embedded within its hierarchy. As you can see from the example, the associated tenant object is returned in the embedded tenants object list of the lease.

Embedded objects can also be accessed directly using the embedded object resource url, for example, /leases/393/tenants.

If you either create or update an object containing embedded objects, the embedded objects will be either created, updated, or deleted.


Query language

Conditionals

Operator Example
= ?field=value
< ?field=<value
<= ?field=<=value
> ?field=>value
>= ?field=>=value
! ?field=!value
or ?field=<value1|>value2
& ?field=>=value&field=<=value
match ?field=?val*

Subobject query

?object[field]=value

Special fields

Name Example
fields ?fields[0]=*&fields[1]=hidden_field
limit ?limit=10
offset ?offset=10

Errors

Example Error Response

{
    "error": "InvalidArguments",
    "error_desc": "password, email, full_name, user_type",
    "response": {
        "email": "Param required",
        "full_name": "Param required",
        "password": "Param required",
        "user_type": "Param required"
    }
}

Errors are relayed via the HTTP Status Code with additional information included in the response body.

The RentShare API uses the following error codes:

Code Meaning
400 Bad Request – This error is relayed when the request cannot be completed due to a general error or invalid or missing parameters. In the case of invalid parameters the response body’s error type will be InvalidArguments and the response object will contain a list of invalid parameters along with a short description.
401 Unauthorized – This error is relayed when the request is not authorized to perform the desired action. This is usually due to an expired or invalid access_token (ie: api key).
403 Forbidden – This error is relayed when the request has a valid access_token but that access_token does not have the necessary privileges to perform the desired action.
404 Not Found – The specified object or resource could not be found. This is caused by requesting an object by id that either no longer exists or is not in the scope of the api key’s access view.
405 Method Not Allowed – This error is relayed when the requested resource exists but the requested method (ie: POST) is not allowed to be performed on that resource.
429 Too Many Requests – This error is relayed when too many requests have been made too frequently, generally due to overuse of a specific resource.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintanance. Please try again later.

Pay Plugin

<form action="/path/to/your/post/method" method="POST">
  <script
    src="https://rentshare.com/plugins/pay.js"
    data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262"
    data-amount="1000.00"
    data-description="First Month's Rent">
  </script>
</form>

If you want your customers to be able to pay from within your own portal or platform, you can use the fully responsive RentShare Pay plugin. This will embed a RentShare Pay button into your form that will open a payment confirmation modal to allow your customer to enter/re-use their payment method(s), confirm, and pay.

Once a payment is confirmed, the Pay plugin will add a hidden rs_transaction_id form element and automatically submit the form.

On the server side you can validate the rs_transaction_id using the transactions api.

base_url = 'https://api.rentshare.com'
api_key = 'private_key_AWcpDnNBB7oLfNqfQ6g66262'

# Complete the transaction id on the server side
resource_url = base_url+'/transactions/{}'\
    .format( rs_transaction_id )

response = requests.put( resource_url,
  json={ 'status': 'complete' }, auth=( api_key, '' ) )

transaction = response.json()
# Check the status
if transaction['status'] != 'complete':
    # handle invalid payment
else:
    # handle successful payment

For a more seamless experience you can create persistent customer accounts which will allow customers to access their stored payment methods across all devices.

Example

Below is an example of the pay plugin. You can click the pay button to see an example of the modal.


RentShare.pay.open({
    key: "public_key_AWcpDnNBB7oLfNqfQ6g66262",
    access_token: "${access_token}",
    on: {
        autopay_changed: function (data) {
            // handle callback
        }
    }
})

You can also launch the plugin from javascript instead of using the embeded html button by calling RentShare.pay.open() as seen in the example.


Persistent Accounts

Persistent accounts allow customers to access their stored payment methods across all devices for a more seamless experience.

# Create a tenant account
base_url = 'https://api.rentshare.com'
api_key = 'private_key_AWcpDnNBB7oLfNqfQ6g66262'
accnt_access_key = 'some_random_key1'

# payer/user account details
payer = {
    'email': 'payer.email@gmail.com',
    'access_key': accnt_access_key,
    'user_type': 'tenant',
    'full_name': 'Payer Name'
}

# create the account on rentshare
response = requests.post( base_url + '/accounts/',
  json=payer, auth=(api_key,'') )

account = response.json()
account_access_token = account['access_token']['access_token']
# At this point store the account['id'] and account_access_token for use later

Create an account

First you need to create a tenant account with the customer’s email, name, and an access key. The access key does not have to be unique across accounts.

Once an account has been created you’ll need to store the account['id'] of the resulting RentShare account.


Creating a session access token

# Create an access_token to pass to the Pay plugin
access_token_req = { 'type': 'session_access' }

resource_url = base_url+'/accounts/{}/access_tokens'\
  .format( account['id'] )

response = requests.post( resource_url, json=access_token_req,
  auth=( account_access_token, '' ) )

access_token = response.json()['access_token']

To load the Pay plugin with a customer’s persistent account, you need to create a unique access-token for your customer. To create an access-token you need to pass the account’s access_key in the password field of the http auth header. You’ll need to create a new access-token every time a new Pay button is loaded.


Launching the Pay plugin

<!-- Then when you render the plugin, pass the access token. Note: the access_token only works once -->
<form action="/path/to/your/post/method" method="POST">
  <script
    src="https://rentshare.com/plugins/pay.js"
    data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262"
    data-amount="1000.00"
    data-description="First Month's Rent"
    data-access-token="${access_token}">
  </script>
</form>

Once you’ve created a new access-token, you can pass it to the Pay plugin using the data-access-token parameter. Once your customer clicks the button, their persistent account will load with any of their stored payment methods or settings.


Autopay

If you are using the Pay plugin with the autopay option you can access the list of payers who enroll using the plugin via the api and with that create a task or trigger to initiate any payments due automatically.

Example button

<!-- Then when you render the plugin, pass the access token. Note: the access_token only works once -->
<script
  src="https://rentshare.com/plugins/pay.js"
  data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262"
  data-access-token="${access_token}"
  data-autopay-only="true">
</script>


Get Current Enrollments

base_url = 'https://api.rentshare.com'
api_key = 'private_key_AWcpDnNBB7oLfNqfQ6g66262'

response = requests.get( base_url + '/autopay_enrollments/',
  auth=( api_key, '' ) )
autopayers = response.json()

First, pull a list of all enrollments using the api through the /autopay_enrollments endpoint. This will return a list of all payers who enrolled into automatic payments.


Create Payment Objects

payments = []
for enrollment in autopayers:
    payments.append({
        'type': 'charge',
        'amount': 1000, # replace this with the outstanding balance
        'description': 'March Rent',
        'payment_method_id': enrollment['payment_method_id'],
        'payee_id': enrollment['payee_id'],
    })

Second, create a list of payments due to those who’ve enrolled. You can only use the payment_method_id that is defined in each entrollment, otherwise the payment will be rejected.


Process Automatic Payments

# process automatic payments
response = requests.post( base_url + '/transactions/',
  auth=( api_key, '' ), json=payments )
payments = response.json()

for payment in payments:
    if payment['status'] == 'complete':
        # handle complete payment
    else:
        # handle failed payment

Lastly, initiate the paymenst using the /transactions endpoint by posting the payment objects created in the last step. The resulting object list will contain a list of completed or declined payments in the same order as the original payment object list created in the last step.


ACH failures

# pull ach failures
failure_query = {
    'status': 'failed',
    'failed_timestamp': '>2017-05-01'
}
response = requests.get( base_url + '/transactions/',
  auth=( api_key, '' ), params=failure_query )
failed_payments = response.json()

for payment in failed_payments:
    print payment['status_details']
    # returns R01 - INSUFFICIENT FUNDS

Unlike cards, ach payments can fail days after a user initiates the payment. If an ach failure is reported by the originating bank, you can pull information through the API using the example.


Refunds


payment = { 'id': 123, 'amount': 500.00 }
refund_params = {
    'amount': payment['amount'],
    'type': 'refund',
    'reversals': [{
        'source_id': payment['id']
    }]
}

response = requests.post( base_url + '/transactions/',
  auth=( api_key, '' ), json=refund_params )
refund = response.json()

To initiating a refund, you need the original transaction id. The amount can be less than or equal to the net amount of the original transaction less any refunds already processed.


Javascript callbacks

RentShare.pay.on( '.mybutton', 'loaded', function() {
    console.log('event captured')
})
RentShare.pay.on( '.mybutton', 'autopay_changed', function( evt ) {
    if ( evt.autopay )
      console.log('autopay enabled')
    else
      console.log('autopay disabled')
})

If you want to watch for a response from the plugin to see if a certain event was triggered there are a few available callbacks: processing, paid, declined, canceled, autopay_changed, closed, loaded, and error

Loaded

The loaded callback is triggered every time the user opens the Pay plugin popup.

Processing

The processing callback is triggered every time the starts the payment process. This callback is followed by either a paid, canceled, or declined callback.

The paid callback is triggered after a payment has been successfully processed. If this is automatically triggering a form request, no close event will follow.

Event Data Description
transaction_id The transaction id of the completed payment
payments_attempted The number of payment attempts made

Declined

The declined callback is triggered everytime an initiated payment is declined. To make a test declined request on the staging server, you can use the card number 5555-5555-5555-4444.

Event Data Description
declined_message The declined reason message

Canceled

The canceled callback is triggered if the payment confirmation is canceled by the user.

Autopay Changed

The autopay_changed callback is triggered if the autopay enrollement state is changed by the user.

Event Data Description
autopay The enrollment details. If null, the user has unenrolled

Closed

The closed callback is triggered if the user closes the Pay plugin window for any reason, or a successful payment has been made. Note, if this is automatically triggering a form request, no close event will follow a successful payment.

Event Data Description
transaction_id Only present after a successful payment. The transaction id of the completed payment
payments_attempted The number of payment attempts made

Error

The error callback is triggered if an unexpected issue occurs within the plugin.

Event Data Description
error_code The error code

Locking the plugin

RentShare.pay.on( '.mybutton', 'autopay_changed', function( evt ) {
    RentShare.pay.lock()

    $.post('/autopay_flag', { enabled: !!evt.autopay }, function() {
        RentShare.pay.unlock()
    })
})

If you’re making an asynchronous request triggered by a javascript callback, it’s recommended to lock the plugin while processing. This will ensure there no interuptable actions taken by the user.


Configuration

Parameter Description
data-key
required
Your embed api key
data-amount
optional with invoice id
The amount of the payment.
data-description
required
The description of the payment.
data-payee-id Specify the recipient account id of the payment. Not required for accounts with only one deposit account.
data-access-token Load an existing payer’s account settngs. See the persistent accounts section for more information.
data-invoice-id If utilizing the invoice api, pass the desired invoice id.
data-recurring-invoice-id If utilizing the recurring invoice api and autopay, pass the desired recurring invoice id.
data-cards Use true or false to specify if card payments are allowed. Default is true.
data-ach Use true or false to specify if ach payments are allowed. Default is true.
data-email The payer’s email address if available.
data-full-name The payer’s full name if available.
data-autopay Use true or false to specify if autopay is allowed. Default is false.
data-btn-class Custom css class for the pay button.
data-btn-text Custom text for the pay button.

Deposit Plugin

  <script
    src="https://rentshare.com/plugins/deposit.js"
    data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262"
    data-access-token="access_token_AWcpDnNBB7oLfNqfQ6g66262">
  </script>

If you have a landlord platform and are creating an end-to-end integration of RentShare, you’ll need to use the Deposit plugin to capture the deposit details for a new landlord account.

The Deposit plugin will embed a button onto your page that will allow acces to a secure popup modal where a landlord can enter their desired direct deposit details.

Example

Below is an example of the Deposit plugin. You can click the button to see an example of the modal.

Create an Account

base_url = 'https://api.rentshare.com'
api_key = 'api_key_WOLJljPMHgM9ZJpmMvMPgZ_wS-39MXVW'
accnt_access_key = 'some_random_key1'
resource_url = base_url+'/accounts/?fields=*&fields=deposit_accounts'

landlord = {
    'user_type': 'property_manager',
    'email': 'landlord.account@gmail.com',
    'full_name': 'Full Name',
    'access_key': accnt_access_key,
    'deposit_accounts': [{
        'company': 'Example Landlord LLC',
        'phone': '111-222-3333',
        'address': {
            'street_address': '123 Example St',
            'unit_number': '#4',
            'city_state_zip': 'New York, NY 10004'
        }
    }]
}

response = requests.post( resource_url,
  json=landlord, auth=( api_key, '' ) )

account = response.json()
account_access_token = account['access_token']['access_token']

First you need to create a landlord account with the landlord’s email, name, and an access key. The access key does not have to be unique across accounts. You must create at least one deposit account.

Once an account has been created you’ll need to store the account['id'] and the automatically created access_token of the resulting RentShare account.


Load the Deposit button

account_access_token = 'api_key_h895lE3evhzqfOmWttqyry6h3uyjQWX2'
account_id = 1234
access_token_req = { 'type': 'session_access' }
resource_url = base_url+'/accounts/{}/access_tokens'.format( account_id )

response = requests.post( resource_url, json=access_token_req,
  auth=( account_access_token, '' ) )

access_token = response.json()['access_token']
    <script
        src="https://rentshare.com/plugins/deposit.js"
        data-key="public_key_JqZzahBa9Z0exkzbQoEBl8"
        data-access-token="${access_token}">
    </script>

The Deposit plugin requires a new session_access token each time you load the plugin.

To create an access token you can either pass the access_token that was returned with the original account creation response as the username field of the http auth header or you can pass your api key and the account’s access_key in the password field of the http auth header.


Javascript callbacks

RentShare.deposit.on( '.mybutton', 'loaded', function() {
    console.log('event captured')
})

If you want to watch for a response from the plugin to see if a certain event was triggered there are a few available callbacks: deposit_changed, closed, loaded


Configuration

Parameter Description
data-key
required
Your embed api key
data-payee-id Specify the deposit account id. Not required for accounts with only one deposit account.
data-access-token Token for session access to an account. See the access-token section for more information.
data-btn-class Custom css class for the deposit button.
data-btn-text Custom text for the deposit button.

Invoicing

recurring_invoice = {
    'start_date': '2017-01-01',
    'end_date': '2017-12-31',
    'recurring_frequency': 'monthly',
    'invoice_template': {
        'items': [{
            'type': 'rent',
            'amount': 1000
        },{
            'type': 'ammenity',
            'amount': 50,
            'date_incurred': '2017-02-15'
        }],
        'payers': [{
            'account_id': account_id
        }],
        'type': 'rent',
    }
}

response = requests.post( base_url+'/recurring_invoices/',
  json=recurring_invoice, auth=( api_key, '' ) )

recurring_invoice = response.json()

Recurring Invoices

The recurring invoice api is an easy way to setup and manage recurring billing instructions. Invoices can be set to auto-generate based on monthly or weekly schedules and can handle multiple recurring invoice items with varying start dates as well as multiple payers.

You can utilize the Pay plugin’s autopay capabilities along with the recurring invoice api to take advantage of our fully automated autopay system by passing the data-recurring-invoice-id plugin parameter.


Object reference

Units

This endpoint retrieves all units.

Resource

https://api.rentshare.com/units

Embedded Resources

https://api.rentshare.com/units/{id}/leases

https://api.rentshare.com/units/{id}/address

Fields

Object example

{
  "id": 855, 
  "status": "payments_allowed", 
  "address_id": 123, 
  "leases": [], 
  "price": 1000, 
  "building_id": 123, 
  "type": "rental", 
  "billing_account_id": 123, 
  "address": {}, 
  "active": true
}
Parameter Description
id
id
Unique object identifier
status
string
Verification status: payments_allowed, payments_blocked
address_id
int
Id for address object
leases
list
List of lease objects
price
number
Default rent amount for this unit
building_id
int
Id for building object
type
string
Valid values: rental, condo
billing_account_id
int
readonly
Id for billing account object
address
object
readonly
Single address object
active
bool
readonly
Valid values: True, False

Leases

This endpoint retrieves all leases.

Resource

https://api.rentshare.com/leases

Embedded Resources

https://api.rentshare.com/leases/{id}/invoices

https://api.rentshare.com/leases/{id}/conditional_rules

https://api.rentshare.com/leases/{id}/recurring_items

https://api.rentshare.com/leases/{id}/tenants

Fields

Object example

{
  "id": 386, 
  "due_day": 1, 
  "unit_id": 123, 
  "tenants": [], 
  "autogenerate_invoices": true, 
  "recurring_items": [], 
  "end_date": "2016-01-01", 
  "invoices": [], 
  "type": "Acct #ABC-123", 
  "prorated": false, 
  "payments_blocked": false, 
  "reference_id": "Acct #ABC-123", 
  "recurring_frequency": "monthly", 
  "active": true, 
  "conditional_rules": [], 
  "start_date": "2015-06-06", 
  "lease_document": "string", 
  "recurring_invoice_template_id": 123, 
  "recurring_invoice_id": 123, 
  "amount": 1500, 
  "rent_amount": 1000
}
Parameter Description
id
id
Unique object identifier
due_day
int
required
Day of the month rent is due
unit_id
int
required
Id for unit object
tenants
list
required
List of tenant objects
autogenerate_invoices
bool
Denotes whether new invoices will be automatically generated
recurring_items
list
List of invoice_items objects
end_date
date
Date this lease ends
invoices
list
List of invoice objects
type
string
User generated reference for this lease
prorated
bool
If enabled, initial and final charges will be prorated
payments_blocked
bool
Denotes whether payments are allowed on this invoice
reference_id
string
User generated reference for this lease
recurring_frequency
string
Valid values: monthly, weekly
active
bool
None
conditional_rules
list
List of conditional_invoice_items objects
start_date
date
Date this lease begins
lease_document
string
Stored lease document file. Input format: Data URI
recurring_invoice_template_id
int
readonly
Id for recurring invoice template object
recurring_invoice_id
int
readonly
Id for recurring invoice object
amount
number
readonly
Total due on this lease, including other items such as late fees
rent_amount
number
readonly
Rent amount for this lease

Tenants

This endpoint retrieves all tenants.

Resource

https://api.rentshare.com/tenants

Fields

Object example

{
  "id": 451, 
  "lease_id": 123, 
  "phone": "string", 
  "last_name": "Snow", 
  "user_id": 123, 
  "account_id": 123, 
  "first_name": "Jon", 
  "mobile_enabled": true, 
  "recurring_payer_id": 592, 
  "email": "knowsnothing@gmail.com", 
  "name": "string"
}
Parameter Description
id
id
Unique object identifier
lease_id
int
Id for lease object
phone
string
Phone number of resident
last_name
string
readonly: update
Last name of account holder
user_id
int
readonly
Id for user object
account_id
int
readonly
Id for account object
first_name
string
readonly: update
First name of account holder
mobile_enabled
bool
readonly
Denotes if user has push notification capabilities
recurring_payer_id
int
readonly
Id for recurring invoice_payer object
email
email
readonly: update
Email address of account holder
name
string
readonly: update
Full name of resident

Recurring Invoices

This endpoint retrieves all recurring_invoices.

Resource

https://api.rentshare.com/recurring_invoices

Embedded Resources

https://api.rentshare.com/recurring_invoices/{id}/invoices

https://api.rentshare.com/recurring_invoices/{id}/invoice_template

Fields

Object example

{
  "invoice_template": {}, 
  "autogenerate_invoices": true, 
  "end_date": "2017-11-01", 
  "invoices": [], 
  "payee_id": 81, 
  "prorated": true, 
  "recurring_frequency": "monthly", 
  "cycle_offset": 1, 
  "start_date": "2017-11-01", 
  "invoice_template_id": 973
}
Parameter Description
invoice_template
object
required
Single invoice object
autogenerate_invoices
bool
required
Denotes whether new invoices will be automatically generated
end_date
date
End date of the recurring service period
invoices
list
List of invoice objects
payee_id
id
Id for deposit_account object
prorated
bool
If enabled, initial and final charges will be prorated
recurring_frequency
string
Valid values: monthly, weekly
cycle_offset
int
Day of the month rent is due
start_date
date
Start date of the recurring service period
invoice_template_id
id
readonly
None

Invoices

This endpoint retrieves all invoices.

Resource

https://api.rentshare.com/invoices

Embedded Resources

https://api.rentshare.com/invoices/{id}/items

https://api.rentshare.com/invoices/{id}/payers

https://api.rentshare.com/invoices/{id}/payment_records

Fields

Object example

{
  "id": 744, 
  "type": "rent", 
  "due_date": "2015-09-01", 
  "payee_covers_fee": {
    "bank_account_fee": {
      "flat": 1.95, 
      "pct": 0.0
    }, 
    "credit_fee": {
      "flat": 0.0, 
      "pct": 0.0299
    }, 
    "debit_fee": {
      "flat": 0.0, 
      "pct": 0.0299
    }, 
    "bank_account": 1.0, 
    "debit": 1.0, 
    "card": 1.0
  }, 
  "items": [], 
  "recurring_invoice": 123, 
  "payee_id": 123, 
  "payers": [], 
  "accepted_payment_state": "full", 
  "description": "September Rent", 
  "reference_id": "Acct #ABC-123", 
  "payments_blocked": false, 
  "payment_records": [], 
  "amount_unassigned": 200, 
  "pay_by_date": "2015-09-01", 
  "last_payment_date": "2017-11-01 22:20:58", 
  "payee_setup": false, 
  "amount_assigned": 800, 
  "amount_paid": 1000, 
  "completed_date": "2015-09-01", 
  "paid": true, 
  "required_payer_auth_level": 2, 
  "amount": 1000
}
Parameter Description
id
id
Unique object identifier
type
string
required
Invoice type, such as rent, fee, misc, etc.
due_date
date
required
The due date for this invoice
payee_covers_fee:  
bank_account_fee:  
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
credit_fee:  
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
debit_fee:  
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
bank_account
number
readonly
Denotes the fee distribution between payee and payer
debit
number
readonly
Denotes the fee distribution between payee and payer
card
number
readonly
Denotes the fee distribution between payee and payer
 
items
list
required
List of invoice_items objects
recurring_invoice
int
Id for recurring invoice object
payee_id
int
Id for billing account object
payers
list
List of invoice_payers objects
accepted_payment_state
string
Denotes whether this invoice requires payment by all tenants. Can be ‘partial’ or 'full’
description
string
Description for this invoice
reference_id
string
Copied from reference_id defined in lease
payments_blocked
bool
Denotes whether payments are allowed on this invoice
payment_records
list
List of invoice_payment_records objects
amount_unassigned
number
readonly
Amount on this invoice that has not been assigned to individual tenants
pay_by_date
date
readonly
The date this invoice needs to be paid by to reach the payee on time
last_payment_date
datetime
readonly
Date and time of the last payment made on this invoice
payee_setup
bool
readonly
Flag identifying if the payee account can accept payment
amount_assigned
number
readonly
Amount on this invoice that has been assigned to individual tenants
amount_paid
number
readonly
The amount that has been paid by tenants
completed_date
datetime
readonly
Date on which this invoice was paid
paid
bool
readonly
Denotes whether this invoice has been paid
required_payer_auth_level
bool
readonly
Minimum authorisation level for payers on this invoice. Defaults to 2
amount
number
readonly
Amount due on this invoice

Invoice Payers

This endpoint retrieves all invoice_payers.

Resource

https://api.rentshare.com/invoice_payers

Embedded Resources

https://api.rentshare.com/invoice_payers/{id}/payments

Fields

Object example

{
  "id": 404, 
  "first_name": "Jon", 
  "email": "knowsnothing@gmail.com", 
  "access": true, 
  "last_name": "Snow", 
  "last_payment_date": "2015-08-28", 
  "amount_assigned": 1000, 
  "account_id": 123, 
  "invoice_id": 123, 
  "amount_paid": 1000, 
  "paid": true, 
  "payments": [], 
  "active": true, 
  "user_id": 123, 
  "payments_transfered": true, 
  "payments_transfer_date": "2015-09-04"
}
Parameter Description
id
id
Unique object identifier
first_name
string
required
First name of account holder
email
email
required
Email address of account holder
access
bool
required
Denotes whether this payer has been authorized access this invoice
last_name
string
Last name of account holder
last_payment_date
datetime
readonly
The last payment made by this payer for this invoice
amount_assigned
number
readonly
The amount assigned to this payer for this invoice
account_id
int
readonly: update
Id for account object
invoice_id
int
readonly
Id for invoice object
amount_paid
number
readonly
The amount this payer has paid for this invoice
paid
bool
readonly
Denotes whether this payer has paid
payments
list
readonly
List of payment objects
active
bool
readonly
Denotes whether this payer is still active
user_id
int
readonly
Id for user object
payments_transfered
bool
readonly
Denotes whether the payments made by this payer have been transferred to the payee
payments_transfer_date
datetime
readonly
The date on which the payments made by this payer were transferred to the payee

Invoice Items

This endpoint retrieves all invoice_items.

Resource

https://api.rentshare.com/invoice_items

Embedded Resources

https://api.rentshare.com/invoice_items/{id}/assignments

Fields

Object example

{
  "id": 110, 
  "amount": 100, 
  "date_incurred": "2017-11-01 22:20:58", 
  "description": "Wolf Chow", 
  "type": "Shared Expense", 
  "recurring": false, 
  "amount_assigned": 100, 
  "invoice_id": 123, 
  "prorated": false, 
  "assignments": []
}
Parameter Description
id
id
Unique object identifier
amount
number
required
The amount for this invoice item
date_incurred
datetime
Date the invoice item was incurred
description
string
The description for this invoice item
type
string
The type of this invoice item, ie. Rent, Late Fee, etc.
recurring
int
Denotes whether this item recurs monthly or is a one-time item
amount_assigned
number
readonly
The amount of this invoice item that has been assigned to payers
invoice_id
int
readonly: update
Id for invoice object
prorated
bool
readonly
Date the invoice item was incurred
assignments
list
readonly
List of invoice_item_assignments objects

Invoice Item Assignments

This endpoint retrieves all invoice_item_assignments.

Resource

https://api.rentshare.com/invoice_item_assignments

Fields

Object example

{
  "id": 144, 
  "amount": 100, 
  "type": "auto", 
  "account_id": 123, 
  "invoice_id": 123, 
  "payer_id": 123, 
  "item_id": 123
}
Parameter Description
id
id
Unique object identifier
amount
number
required
The amount of this assignment
type
string
required
The type of this assignment. Can be ‘auto’, 'custom’, 'auto_payer’, or 'auto_payee’
account_id
int
readonly
Id for account object
invoice_id
int
readonly
Id for invoice object
payer_id
int
readonly
Id for invoice payer object
item_id
int
readonly
Id for invoice item object

Transactions

This endpoint retrieves all transactions.

Resource

https://api.rentshare.com/transactions

Embedded Resources

https://api.rentshare.com/transactions/{id}/payment_method

https://api.rentshare.com/transactions/{id}/reversals

https://api.rentshare.com/transactions/{id}/transfers

Fields

Object example

{
  "status": "pending", 
  "description": "string", 
  "payment_method": {}, 
  "fee": 1.95, 
  "payment_method_id": 673, 
  "initiated_timestamp": "2017-11-01 22:20:58", 
  "payee_id": 738, 
  "failed_timestamp": "2017-11-01 22:20:58", 
  "amount": 335.77, 
  "settled": true, 
  "status_details": "string", 
  "type": "charge", 
  "account_id": 197
}
Parameter Description
status
string
Valid values: pending, complete, declined, canceled, failed
description
string
Description of the payment
payment_method
object
Single payment_methods object
fee
number
readonly: user_sessions,update
Processing fee
payment_method_id
id
readonly: update
Id for payment_method object
initiated_timestamp
datetime
readonly
Date the payment was initiated
payee_id
int
readonly: update
Id for billing account object
failed_timestamp
datetime
readonly
Date the payment failed (ACH Only)
amount
number
readonly: update
Amount of the payment
settled
bool
readonly
Denotes if the payment has settled
status_details
string
readonly
Additional details on the status of the payment
type
string
readonly: update
Valid values: charge, deposit, reversal, refund, chargeback, chargeback_reversal
account_id
int
readonly: update
Id for account object

Autopay Enrollments

This endpoint retrieves all autopay_enrollments.

Resource

https://api.rentshare.com/autopay_enrollments

Fields

Object example

{
  "upper_limit": 238.42, 
  "payment_method_id": 130, 
  "payee_id": 100, 
  "lower_limit": 819.22, 
  "account_id": 334, 
  "last_payment_timestamp": "2017-11-01 22:20:58", 
  "last_payment_status": "string", 
  "recurring_invoice_id": 650, 
  "enrolled_timestamp": "2017-11-01 22:20:58"
}
Parameter Description
upper_limit
currency
required
Upper limit of how much the user has allowed to auto-process
payment_method_id
int
required
Id for payment_method object
payee_id
int
Id for deposit_account object
lower_limit
currency
Lower limit of how much the user has allowed to auto-process
account_id
int
readonly
Id for account object
last_payment_timestamp
datetime
readonly
Timestamp of the last payment attempt for the account
last_payment_status
string
readonly
Status of the last payment attempt for the account
recurring_invoice_id
id
readonly: update
Id for recurring_invoice object
enrolled_timestamp
datetime
readonly
Timestamp user enrolled in autopay

Accounts

This endpoint retrieves all accounts.

Resource

https://api.rentshare.com/accounts

Embedded Resources

https://api.rentshare.com/accounts/{id}/access_token

https://api.rentshare.com/accounts/{id}/deposit_accounts

Fields

Object example

{
  "user_type": "tenant", 
  "full_name": "Jon Snow", 
  "email": "knowsnothing@gmail.com", 
  "access_key": "string", 
  "accepted_terms": false, 
  "company": "string", 
  "phone": "(123) 456-7890", 
  "user_id": 232
}
Parameter Description
user_type
string
required
Valid values: tenant, property_manager
full_name
string
required
Name of account holder
email
email
required
Email address of account holder
access_key
string
A secret key (password) used to create an access_token
accepted_terms
bool
Flag for if the user has accepted the user agreement
company
string
Company name of account holder
phone
phone
Phone number of account holder
user_id
id
readonly
User id of account holder

Deposit Accounts

This endpoint retrieves all deposit_accounts.

Resource

https://api.rentshare.com/deposit_accounts

Embedded Resources

https://api.rentshare.com/deposit_accounts/{id}/deposit_method

https://api.rentshare.com/deposit_accounts/{id}/address

Fields

Object example

{
  "id": 353, 
  "company": "string", 
  "address": {}, 
  "fee_settings": {
    "credit": {
      "alloc": 0.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }, 
    "bank_account": {
      "alloc": 1.0, 
      "flat": 1.95, 
      "pct": 0.0
    }, 
    "debit": {
      "alloc": 0.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }
  }, 
  "phone": "(123) 456-7890", 
  "deposit_method": {}, 
  "accepted_terms": false, 
  "deposit_method_id": 957, 
  "address_id": 361, 
  "user_id": 938, 
  "default": false
}
Parameter Description
id
id
Unique object identifier
company
string
required
Company name of deposit account
address
object
required
Single address object
fee_settings:  
credit:  
alloc
number
Denotes the fee allocation between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
bank_account:  
alloc
number
Denotes the fee allocation between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
debit:  
alloc
number
Denotes the fee allocation between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
 
phone
phone
required
Phone number associated with the deposit account
deposit_method
object
Single payment_methods object
accepted_terms
bool
Flag for if the signer has accepted the processing agreements
deposit_method_id
int
Id for payment_method object
address_id
id
readonly
Id for address object
user_id
id
readonly
Id for payment_method object
default
bool
readonly
Denotes if this account is the user’s specified default

Access Token

This endpoint retrieves all access_token.

To create an access token the account holder’s secret key is required to be passed via HTTP Basic Auth.

Example create

curl -X POST "https://api.rentshare.com/accounts/43242/account_token"
   -u api_key_6fsMi3GDxXg1XXSluNx1sLEd:secret_key_JIgOLxPqSV9bROAL

Resource

https://api.rentshare.com/access_token

Fields

Object example

{
  "type": "private_key", 
  "expiration": "2017-11-01 22:20:59", 
  "access_token": "string", 
  "account_id": 965
}
Parameter Description
type
string
required
Valid values: private_key, user, session_access, public_key
expiration
datetime
Date and time access token will expire
access_token
string
readonly
Access token to be used for api access
account_id
int
readonly
Id for account object

Events

This endpoint retrieves all events.

Resource

https://api.rentshare.com/events

Fields

Object example

{
  "callback_url": "https://example.com/ach_failure_handler", 
  "event": "ach_failure"
}
Parameter Description
callback_url
string
required
Url to trigger
event
string
required
Name of event