NAV Navbar
Logo
JSON

Introduction

Welcome to the Rent Prep SmartMove API. You can use this API to submit credit report applications for your customer's on behalf of your company once you've established an API Account with Rent Prep.

The general flow of a credit report application is as follows:

  1. Request a credit report for tenants
  2. Receive a link to create the credit report
  3. Emails are sent to each tenant requesting action be taken as well as the landlord to confirm the order
  4. Tenant will accept or reject the application and complete their part of the application
  5. Reports will become available

When requesting an order you must supply the unique ID for your user from your system, as well as any optional data about your user, property, applicants, etc which will pre-populate the application creation form.

API Locations

Sandbox

The Sandbox API location is https://stage.rentprep.com

Production

The Production API location is https://screen.rentprep.com

Setting Up the SmartMove PHP Library

A PHP library is supplied to make using the API as simple as possible. All of the code examples in this document will be using the library.

The library can be downloaded from https://github.com/rentprep/smartmove-php which includes even more documentation on how to use it.

Requirements

PHP 5.3.3 and later.

Installation

Composer

You can install the library via Composer. Run the following command:

composer require rentprep/rentprep-php

To use the library, use Composer's autoload:

require_once('vendor/autoload.php');

Manual

If you do not wish to use Composer, you can download the latest release. Then, to use the library, include the init.php file.

require_once('/path/to/rentprep-php/init.php');

Authentication

To authorize, provide your API Key in the Request Header "x-apiKey":

Make sure to replace 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' with your API key.

Rent Prep uses API keys to allow access to the API. You can register for a new Rent Prep API key by contacting us.

Rent Prep expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-apiKey: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Using the SmartMove PHP Library, set your API key using the following:

use RentPrep\RentPrep;

RentPrep::setApiKey('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');

Endpoints

Create Application

An example POST request will have a payload that looks like this

{
    "Product": "PackageCorePlusEviction",
    "Application": {
        "Applicants": ["[email protected]", "[email protected]"],
        "declineForOpenBankruptcies": false,
        "openBankruptcyWindow": 0
    },
    "Customer": {
        "referenceId": "123"
    },
    "Property": {
        "LandlordCity": "Springfield",
        "LandlordFirstName": "Homer",
        "LandlordLastName": "Simpson",
        "LandlordPhoneNumber": "5555555555",
        "LandlordState": "NY",
        "LandlordStreetAddressLineOne": "123 Fake Street",
        "LandlordZip": "12345",
        "LandlordEmail": "[email protected]",
        "Street": "123 Property Street",
        "City": "Springfield",
        "State": "NY",
        "Zip": "12345",
        "UnitNumber": "4",
        "PropertyName": "742 Evergreen Terrace",
        "Classification": "Conventional"
    },
    "RequestParameters": {
        "postbackUri": "http://yoursite.com",
        "postback_password": "",
        "postback_username": "",
        "referenceId": ""
    }
}

A successful call returns a unique link that the customer must use to finish creating the application. It will look like this

"https://stage.rentprep.com/smartmove/api/create/VVVWUnBaeUdlZzJWR0ZqWjd5MVFOclZnNk9EWjRkVzB6dUkzZ3FTU3A5dz01/WjNNVnJFMFlORFV0ZW04MFQ3dHRUZlVScS92dEwvM1J2N0Q1VERNcmNCMD01/dE9uL3pUMysyUW9IWjFuRHZNUHJCTDQzblB1VFdaN1Zxb0dibFNteEFBVWROV0dvSWVHd3k2UWRPcUtqVHNBQmtmaDcrOUdEdzUyL0tPUkR2ZzFYb1E9PQ2"

Create an application by posting a valid OrderRequest object to the /api/smartmove/application/create endpoint.

HTTP Request

POST /api/smartmove/application/create

There are 4 components to a OrderRequest:

Model Definition

Parameter Description Type Requirements
Application The details of the application Application Optional
Product The product being ordered Product Optional
Customer The customer creating the order Customer Required
Property The property details Property Optional
RequestParameters Additional Request Parameters RequestParameters Optional
  1. Application Contains the details of the renter application including the applicants, the unit number, payment responsibility, etc.
  2. Product The product type being ordered. Current available option is 'PackageCorePlusEviction'
  3. Customer This model contains the unique ID from your system of your customer placing the order.
  4. Property This model contains all of the details of the Property
  5. RequestParameters These parameters accompany your API order to define variables related to the order and how to respond to your postback endpoint. postbackUri is required and will be used to send your order report data. If you supply values for postback_username and postback_password, the postback message will add an 'Authorization’ header as follows: Authorization: base64encodedUsername:base64encodedPassword

HTTP Response

Your screening order POST will result in either an error response with an error description, or a 200 Success response accompanied by a link to complete the application with any supplied information already filled in.

The user should be redirected to this URL to complete the required form and create the application.

Receiving Postback Data

If you’ve successfully placed an order using the /api/smartmove/application/create/embedded endpoint with RequestParameters, notifications about the status of the renters and application will be posted to the endpoint you provided in the RequestParameters postbackUri property.

The message will come in the form of a application/json POST.

An example Postback message

{
    "applicationId": 000000,
    "customerReferenceId": "123",
    "notificationText": "[email protected] has accepted the request",
    "reportStatus": "InProgress",
    "referenceId": null
}

POST data

The returned json properties are:

applicationId - The application ID

customerReferenceId - The internal ID for your end user

notificationText - The notification message

reportStatus - The status of the report

referenceId - Any custom ID you posted

referenceText - Any text you included to be included in the post back

Create Application Natively

An example POST request will have a payload that looks like this

{
    "Product": "PackageCorePlusEviction",
    "Application": {
        "Applicants": ["[email protected]", "[email protected]"],
        "declineForOpenBankruptcies": false,
        "openBankruptcyWindow": 0,
        "LandlordPays": true
    },
    "Customer": {
        "referenceId": "123"
    },
    "Property": {
        "LandlordCity": "Springfield",
        "LandlordFirstName": "Homer",
        "LandlordLastName": "Simpson",
        "LandlordPhoneNumber": "5555555555",
        "LandlordState": "NY",
        "LandlordStreetAddressLineOne": "123 Fake Street",
        "LandlordZip": "12345",
        "LandlordEmail": "[email protected]",
        "Street": "123 Property Street",
        "City": "Springfield",
        "State": "NY",
        "Zip": "12345",
        "UnitNumber": "4",
        "PropertyName": "742 Evergreen Terrace",
        "Classification": "Conventional",
        "IsFcraAgreementAccepted": true
    },
    "CreditCard": {
        "firstName": "Homer",
        "lastName": "Simpson",
        "cardType": "mastercard",
        "cardNumber": "5419543578415880",
        "cardSecurity": "554",
        "expireMonth": "09",
        "expireYear": "2022"
    },
    "RequestParameters": {
        "postbackUri": "http://yoursite.com",
        "postback_password": "",
        "postback_username": "",
        "referenceId": ""
    }
}

This endpoint uses the same model as the /api/smartmove/application/create/ endpoint with an added CreditCard model and optional 'RequestParameters' model.

A successful call returns a 200 response with the Application ID. Emails will be sent out to the landlord and applicants upon successful creation.

Create an application by posting a valid OrderRequest object to the /api/smartmove/application/create/embedded endpoint.

HTTP Request

POST /api/smartmove/application/create/embedded

There are 5 components to a OrderRequest:

Model Definition

Parameter Description Type Requirements
Application The details of the application Application Required
Product The product being ordered Product Required
Customer The customer creating the order Customer Required
Property The property details Property Required
CreditCard The credit card details CreditCard Required if LandlordPays is true
RequestParameters Additional Request Parameters RequestParameters Optional
  1. Application Contains the details of the renter application including the applicants, the unit number, payment responsibility, etc.
  2. Product The product type being ordered. Current available option is 'PackageCorePlusEviction'
  3. Customer This model contains the unique ID from your system of your customer placing the order.
  4. Property This model contains all of the details of the Property
  5. CreditCard This model contains all of the details of the landlord credit card
  6. RequestParameters These parameters accompany your API order to define variables related to the order and how to respond to your postback endpoint. postbackUri is required and will be used to send your order report data. If you supply values for postback_username and postback_password, the postback message will add an 'Authorization’ header as follows: Authorization: base64encodedUsername:base64encodedPassword

HTTP Response

Your screening order POST will result in either an error response with an error description, or a 200 Success response with the Application ID if the application was succesfully created.

Upon success, emails will be sent out to the applicants and the landlord with further instructions.

Receiving Postback Data

If you’ve successfully placed an order using the /api/smartmove/application/create/embedded endpoint with RequestParameters, notifications about the status of the renters and application will be posted to the endpoint you provided in the RequestParameters postbackUri property.

The message will come in the form of a application/json POST.

An example Postback message

{
    "applicationId": 000000,
    "customerReferenceId": "123",
    "notificationText": "[email protected] has accepted the request",
    "reportStatus": "InProgress",
    "referenceId": null
}

POST data

The returned json properties are:

applicationId - The application ID

customerReferenceId - The internal ID for your end user

notificationText - The notification message

reportStatus - The status of the report

referenceId - Any custom ID you posted

referenceText - Any text you included to be included in the post back

Delete Applicant

{
    "applicationId": 12345,
    "referenceId": 1,
    "email": "[email protected]"
}

Delete an applicant from a SmartMove application.

An applicant can only be removed from an application if the following criteria are met:

  1. Them applicant being removed has not responded to their application request.
  2. The applicant being removed is not the only applicant on the application.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required
email The email of the tenant you'd like to delete from the application string Required

HTTP Request

POST /api/smartmove/applicant/delete

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response.

Add Applicant

{
    "applicationId": 12345,
    "referenceId": 1,
    "email": "[email protected]"
}

Add an applicant to the application.

An applicant can only be added to an application if the following criteria are met:

  1. The payment responsibility must be the tenants and not the landlord.
  2. The application must not be completed.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required
email The email of the tenant you'd like to add from the application string Required

HTTP Request

POST /api/smartmove/applicant/add

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response.

Get Application Details

{
    "applicationId": 12345,
    "referenceId": 1
}

A successful call returns a a JSON object containing the details of the application

{
    "ApplicationId": 12345,
    "LandlordPays": true,
    "Property": {
        "PropertyId": 12345,
        "Name": "742 Evergreen Terrace",
        "PropertyIdentifier": "123 Property Street",
        "UnitNumber": "4",
        "Street": "123 Property Street",
        "City": "Springfield",
        "State": "NY",
        "Zip": "12345"
    },
    "Status": "Active",
    "Applicants": [
        {
            "AccountId": 0,
            "FirstName": "Lisa",
            "LastName": "Simpson",
            "MiddleName": null,
            "EmailAddress": "[email protected]",
            "EmploymentIncome": 100,
            "EmploymentIncomePeriod": 1,
            "EmploymentStatus": "Employed",
            "OtherIncome": 0,
            "OtherIncomePeriod": 1,
            "RequestCreatedDate": "2017-11-10T14:44:56.79",
            "RequestExpirationDate": "2018-01-09T14:44:56.79",
            "ApplicantStatus": "NoActivity",
            "Assets": 0,
            "CreditReport": null,
            "CriminalRecords": null,
            "EvictionRecords": null,
            "ExtraElements": null,
            "ParsingErrors": null
        },
        {
            "AccountId": 0,
            "FirstName": "Marge",
            "LastName": "Simpson",
            "MiddleName": null,
            "EmailAddress": "[email protected]",
            "EmploymentIncome": 12555,
            "EmploymentIncomePeriod": 1,
            "EmploymentStatus": "Employed",
            "OtherIncome": 0,
            "OtherIncomePeriod": 0,
            "RequestCreatedDate": "2017-11-10T14:44:56.807",
            "RequestExpirationDate": "2018-01-09T14:44:56.807",
            "ApplicantStatus": "NoActivity",
            "Assets": 0,
            "CreditReport": null,
            "CriminalRecords": null,
            "EvictionRecords": null,
            "ExtraElements": null,
            "ParsingErrors": null
        }
    ],
    "CreditRecommendation": 0,
    "CreditRecommendationPolicyText": "Unavailable",
    "SelectedBundle": 0
}

CreditRecommendation values can be found here.

ApplicantStatus values can be found here

Get a single application's details.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required

HTTP Request

POST /api/smartmove/application/details

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response with the order details

Get All Applications

{
    "referenceId": 1,
    "limit": 10,
    "page": 1
}

A successful call will return an array of JSON application objects sorted by newest first

[
    {
        "ApplicationId": 23456,
        "Applicants": ["[email protected]"],
        "UnitNumber": null,
        "LandlordPays": false,
        "Property": {
            "PropertyId": 12345,
            "Name": "742 Evergreen Terrace",
            "PropertyIdentifier": "123 Property Street",
            "UnitNumber": "4",
            "Street": "123 Property Street",
            "City": "Springfield",
            "State": "NY",
            "Zip": "12345"
        },
        "Status": "InProgress",
        "RenterStatuses": null,
        "PaymentStatuses": [
            {
                "emailAddress": "[email protected]",
                "didAccept": null,
                "orderPaymentId": null
            }
        ],
        "IsCancellable": true,
        "CanAddApplicants": true
    },
    {
        "ApplicationId": 45678,
        "Applicants": ["[email protected]"],
        "UnitNumber": null,
        "LandlordPays": false,
        "Property": {
            "PropertyId": 12345,
            "Name": "742 Evergreen Terrace",
            "PropertyIdentifier": "123 Property Street",
            "UnitNumber": "4",
            "Street": "123 Property Street",
            "City": "Springfield",
            "State": "NY",
            "Zip": "12345"
        },
        "Status": "InProgress",
        "RenterStatuses": null,
        "PaymentStatuses": [
            {
                "emailAddress": "[email protected]",
                "didAccept": null,
                "orderPaymentId": null
            }
        ],
        "IsCancellable": true,
        "CanAddApplicants": true
    }
]

Get all applications created by a customer.

The 'limit' and 'page' parameters are useful for paginating this data in a table.

Model Definition

Parameter Description Type Requirements
referenceId Your customer's unique customer ID string Required
limit Limit the number of results returned. Default is 10 if no limit given int Optional
page The current page of data for paginated data. Will offset results using page*limit int Optional

HTTP Request

POST /api/smartmove/application/all

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response with a JSON array of the orders.

Cancel Application

{
    "applicationId": 12345,
    "referenceId": 1
}

Cancel a SmartMove application.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required

HTTP Request

POST /api/smartmove/application/cancel

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response.

Get Report URL

{
    "applicationId": 12345,
    "referenceId": 1
}

A Successful response will return a unique link that allows the landlord to view the generated reports

"https://stage.rentprep.com/smartmove/api/application/report/WVc4ZVNySlJkeUJsSy9GUUFxY0tBzzZzls5jNEMWQ3SjduQitiZz01/NzRTV1ZPZXRGdHZ6VDBReUdLMVBnZjdtZTM5Y3dN2NkcadkZ3ZkdENpYz01"

Get a link to the Report for an application.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required

HTTP Request

POST /api/smartmove/application/reportUrl

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response accompanied by a link to view the report.

Get Report Status

{
    "applicationId": 12345,
    "referenceId": 111
}

Get the status of the reports for the application.

A successful call will return the report status as a string

"Pending"

Report statuses can be found here.

Model Definition

Parameter Description Type Requirements
applicationId The SmartMove application ID int Required
referenceId Your customer's unique customer ID string Required

HTTP Request

POST /api/smartmove/application/report/status

HTTP Response

Your screening order POST will result in either an error response with a 400 response and an error description, or a 200 Success response with the report status

Models

OrderRequest

{
    "Product": "PackageCorePlusEviction",
    "Application": {
        "Applicants": ["[email protected]", "[email protected]"],
        "declineForOpenBankruptcies": false,
        "openBankruptcyWindow": 0
    },
    "Customer": {
        "referenceId": "123"
    },
    "Property": {
        "LandlordCity": "Springfield",
        "LandlordFirstName": "Homer",
        "LandlordLastName": "Simpson",
        "LandlordPhoneNumber": "5555555555",
        "LandlordState": "NY",
        "LandlordStreetAddressLineOne": "123 Fake Street",
        "LandlordZip": "12345",
        "LandlordEmail": "[email protected]",
        "Street": "123 Property Street",
        "City": "Springfield",
        "State": "NY",
        "Zip": "12345",
        "PropertyName": "742 Evergreen Terrace",
        "Classification": "Conventional",
        "IsFcraAgreementAccepted": true
    }
}

Model Definition

Parameter Description Type Requirements
Application The details of the application Application No
Product The product type being ordered Product No
Customer The landlord creating the order Customer Required
Property The property details Property No

Application

{
    "Applicants": ["[email protected]", "[email protected]"],
    "declineForOpenBankruptcies": false,
    "openBankruptcyWindow": 0,
    "LandlordPays": true
}

Details about the application

Model Definition

Parameter Description Type Requirements
Applicants An array of tenant email addresses string[] Optional (Required if using /application/create/embedded endpoint)
LandlordPays Does the landlord pay for the application boolean Optional (Required if using /application/create/embedded endpoint)
declineForOpenBankruptcies Decline applicants with open bankruptcies boolean Optional (Required if using /application/create/embedded endpoint)
openBankruptcyWindow How many months to look back for open bankruptcies (Between 6 and 120) int Optional (Required if declineForOpenBankruptcies is true)

Customer

{
    "referenceId": "1"
}

The unique data related to your end user.

Model Definition

Parameter Description Type Requirements
referenceId Your internal ID for this end user string (100) Required

Product

The product you want to order

Enum Values

Name Description
PackageCorePlusEviction Credit, credit recommendation, criminal reports, and eviction reports

Property

{
    "LandlordCity": "Springfield",
    "LandlordFirstName": "Homer",
    "LandlordLastName": "Simpson",
    "LandlordPhoneNumber": "5555555555",
    "LandlordState": "NY",
    "LandlordStreetAddressLineOne": "123 Fake Street",
    "LandlordZip": "12345",
    "LandlordEmail": "[email protected]",
    "Street": "123 Property Street",
    "City": "Springfield",
    "State": "NY",
    "Zip": "12345",
    "PropertyName": "742 Evergreen Terrace",
    "Classification": "Conventional",
    "IsFcraAgreementAccepted": true //(see below)
}

The details of the property and your user.

Model Definition

Parameter Description Type Requirements
LandlordFirstName The first name of the landlord string(50) Optional (Required if using /application/create/embedded endpoint)
LandlordLastName The last name of the landlord string(50) Optional (Required if using /application/create/embedded endpoint)
LandlordStreetAddressLineOne The street address of the landlord string(100) Optional (Required if using /application/create/embedded endpoint)
LandlordStreetAddressLineTwo The street address line two of the landlord string(100) Optional
LandlordCity The city of the landlord string(100) Optional (Required if using /application/create/embedded endpoint)
LandlordState The state of the landlord. For domestic addresses use the USPS 2-letter state abbreviation string(2) Optional (Required if using /application/create/embedded endpoint)
LandlordZip The postal code of the landlord string (5) Optional (Required if using /application/create/embedded endpoint)
LandlordPhoneNumber The phone number of the landlord string (15) Optional (Required if using /application/create/embedded endpoint)
LandlordPhoneExtension The phone extension of the landlord string (6) Optional
LandlordEmail The email address of the landlord string (100) Optional (Required if using /application/create/embedded endpoint)
UnitNumber The property unit number string(50) Optional (Required if using /application/create/embedded endpoint)
Street The property street address string(100) Optional (Required if using /application/create/embedded endpoint)
PropertyName The property name string(50) Optional (Required if using /application/create/embedded endpoint)
City The property city string(50) Optional (Required if using /application/create/embedded endpoint)
State The property state abbreviation string(2) Optional (Required if using /application/create/embedded endpoint)
Zip The property zip code string(5) Optional (Required if using /application/create/embedded endpoint)
Classification The property classification Classification Optional (Required if using /application/create/embedded endpoint)
IsFcraAgreementAccepted Did the user accept the FCRA Agreement bool Only required for /application/create/embedded endpoint. Not used for any others.

RequestParameters

{
    "postbackUri": "https://yourpostbackurl.com/postback",
    "postback_password": "",
    "postback_username": "",
    "referenceId": "555",
    "referenceText": "",
    "sendCustomerReceipt": false
}

Information related to your environment, systems, and API

The postbackUri is vital. This is the Uri on your end which will accept the json POST Response Message containing the report data.

If you provide a postback_username and postback_password they will be used in the Response Message in the form of an Authorization header with the username and password base64 encoded Authorization: base64encodedUsername:base64encodedPassword

Model Definition

Parameter Description Type Requirements
postbackUri The URI to your postback handler where the reports will be sent string Optional
postback_username The username value to be sent back as Basic Authentication to your postback endpoint string Optional
postback_password The password value to be sent back as Basic Authentication to your postback endpoint string Optional
referenceId Any reference ID value you’d like included with the postback messages i.e. your internal order ID string Optional
referenceText Any arbitrary text value you’d like included with the postback messages string Optional
sendCustomerReceipt future implementation should Rent Prep send an order receipt to the supplied Customer email address bool Optional

Classification

The property classification

Enum Values

Name Description
Conventional A conventional property
Subsidized A subsidized property

Credit Card

{
    "firstName": "Homer",
    "lastName:": "Simpson",
    "cardType": "mastercard",
    "cardNumber": "5419543578415880",
    "cardSecurity": "554",
    "expireMonth": "09",
    "expireYear": "2022"
}

The details of the landlord's credit card

Model Definition

Parameter Description Type Requirements
firstName The first name of the cardholder string(50) Required
lastName The last name of the cardholder string(50) Required
cardType Credit card type CreditCardType Required
cardNumber Credit card number string(16) Required
cardSecurity Credit card security number string(5) Required
expireMonth Credit card expiration month string(2) Required
expireYear Credit card expiration year string(4) Required

CreditCardType

Credit card type

Enum Values

Name Description
visa Visa
amex American Express
discover Discover card
mastercard MasterCard

Report Status

Report status values found in Application Details

Enum Values

Values Description
Pending Pending
Ready Report ready
InProgress The report is in progress
RequestDeclined Credit report request was declined
Error A report error occurred
Expired Expired

CreditRecommendation

Credit recommendation values found in Get Application Details

Enum Values

Values Description
0 Unavailable
1 Accept
2 Low Accept
3 Conditional
4 Decline
5 Refer
6 Pending

ApplicantStatus

ApplicantStatus values found in Get Application Details

Enum Values

Values Description
NoActivity The applicant has not accepted or rejected the application yet
RequestAccepted The applicant has accepted but has not completed the application
RequestDeclined The applicant has rejected the order
IDMACompleted The applicant has accepted and has completed the verification questions
ReportsRequested The applicant has completed the application fully and the credit report is in progress
ReportsAvailable The applicant has completed the application fully and the report is ready for viewing
SupportRequired The applicant has a conflict and must call Transunion directly to complete the application