Introduction

Welcome to the Rent Prep Screening API. You can use this API to submit screening orders for your company and on behalf of your customers once you’ve established an API Account with Rent Prep.

The general flow of a screening order is as follows:

1. Place a new screening order
2. Receive a success or error response to the submission
3. Receive 1 or more postback responses to your defined endpoint
4. Update your system with the posted data

When placing a new screening order you will supply the details required to process the screening report as well as information about your client, payment information, and API postback information.

As your screening order moves through review, messages will be posted to the endpoint you provide in the RequestParameters postbackUri property. The message will come in the form of a multipart/form-data POST which will contain several variables as well as the latest screening report in PDF form.

Your endpoint will be posted to many times (usually 5 – 7 times), each time with the updated screening report in PDF form.

API Locations

Sandbox

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

Production

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

Authentication

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

using (var httpClient = new HttpClient())
{
    httpClient.DefaultRequestHeaders.Add("x-apiKey","00000000-0000-0000-0000-000000000000");
}

Make sure to replace ‘00000000-0000-0000-0000-000000000000’ 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: 00000000-0000-0000-0000-000000000000

Screening

Create A Screening Order

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

{
    "PackageName": "Platinum",
    "Customer": {
        "CreditCard": {
            "cardNumber": "5419543578415880",
            "cardSecurity": "554",
            "cardType": "mastercard",
            "expireMonth": "09",
            "expireYear": "2020"
        },
        "IPAddress": "127.0.0.1",
        "billingCity": "Buffalo",
        "billingState": "NY",
        "billingStreetAddress": "567 Customer Street",
        "billingZip": "14210",
        "company": "My Company Co.",
        "emailAddress": "jcustomer@email.com",
        "firstName": "John",
        "lastName": "Customer",
        "phone": "9991129999",
        "referenceId": "7"
    },
    "Applicant": {
        "city": "Buffalo",
        "dateOfBirth": "1981-10-12",
        "emailAddress": "",
        "fax": "",
        "firstName": "Hank",
        "lastName": "Mess",
        "middleName": "",
        "phone": "716-204-9999",
        "postalCode": "14210",
        "ssn": "333-22-1111",
        "state": "NY",
        "streetAddress": "567 Some Street"
    },
    "CurrentLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "Employer": {
        "companyName": "Geico",
        "phone": "716-204-9999",
        "supervisorFirstName": "Warren",
        "supervisorLastName": "Buffet"
    },
    "PreviousLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "RequestParameters": {
        "postbackUri": "https://yourpostbackurl.com/postback",
        "postback_password": "",
        "postback_username": "",
        "referenceId": "",
        "referenceText": "",
        "sendCustomerReceipt": false
    }
}

The above command returns a BackgroundScreeningOdrer object as JSON structured like this:

{
    "packageName": "Platinum",
    "Customer": {
        "CreditCard": {
            "cardNumber": "XXXXXXXXXXXX5880",
            "cardSecurity": "",
            "cardType": "mastercard",
            "expireMonth": "09",
            "expireYear": "2020"
        },
        "IPAddress": "127.0.0.1",
        "billingCity": "Buffalo",
        "billingState": "NY",
        "billingStreetAddress": "567 Customer Street",
        "billingZip": "14210",
        "company": "My Company Co.",
        "emailAddress": "jcustomer@email.com",
        "firstName": "John",
        "lastName": "Customer",
        "phone": "9991129999",
        "referenceId": "7"
    },
    "Applicant": {
        "city": "Buffalo",
        "dateOfBirth": "1981-10-12T00:00:00",
        "emailAddress": "",
        "fax": "",
        "firstName": "Hank",
        "lastName": "Mess",
        "middleName": "",
        "phone": "716-204-9999",
        "postalCode": "14210",
        "ssn": "XXXXXXX1111",
        "state": "NY",
        "streetAddress": "567 Some Street"
    },
    "CurrentLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "Employer": {
        "companyName": "Geico",
        "phone": "716-204-9999",
        "supervisorFirstName": "Warren",
        "supervisorLastName": "Buffet"
    },
    "PreviousLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "RequestParameters": {
        "postbackUri": "https://yourpostbackurl.com/postback",
        "postback_password": "",
        "postback_username": "",
        "referenceId": "",
        "referenceText": "",
        "sendCustomerReceipt": false
    }
}

Create a screening order by posting a valid BackgroundScreeningOrder object to the /api/screen/backgroundcheck endpoint.

HTTP Request

POST /api/screen/backgroundcheck

There are 7 components to a BackgroundScreeningOrder request:

Model Definition

Parameter	Description	Type	Requirements
packageName	The Screening Package you are ordering	ScreeningPackage	Required
Customer	Your customer who is placing the screening order	Customer	Required
Applicant	The Applicant being screened	Applicant	Required
CurrentLandlord	The Applicant’s current landlord	Landlord	Platinum Package Only
PreviousLandlord	The Applicant’s previous landlord	Landlord	Platinum Package Only
Employer	The Applicant’s current employer	Employer	Platinum Package Only
RequestParameters	Additional Request Parameters	RequestParameters	Required

1. packageName Specifies which package is being ordered. Available options are 'Basic’, 'Pro’, 'Platinum’, 'CorpWithCredit’, 'CorpCreditOnly’. The package being ordered determines the cost and which components are required to process a successful screening report. Only the Platinum Package requires the CurrentLandlord, PreviousLandlord, and Employer components. CorpWithCredit and CorpCreditOnly are for Corporate accounts which have been pre-arranged with RentPrep ONLY.
2. Customer The Customer model contains the details of your customer including their payment information. Their credit card will be charged when a screening order is placed (unless in the sandbox). You should use the referenceId field to provide your internal ID for the customer so that the RentPrep transaction can be tied to a customer ID in your system.
3. Applicant The Applicant is the individual being screened by your customer. All fields are required except 'middleName’, 'fax’, 'emailAddress’.
4. CurrentLandlord Premium Package Only The Applicant’s current landlord information. All fields are required except 'comments’, 'fax’, 'emailAddress’.
5. PreviousLandlord Premium Package Only The Applicant’s previous landlord information. All fields are required except 'comments’, 'fax’, 'emailAddress’.
6. Employer Premium Package Only The Applicant’s current Employer for verification. All fields are required.
7. RequestParamaters 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 an echo of your BackgroundScreeningOrder object (with sensitive data masked).

Receiving Postback Data

An example Postback message

------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="transactionId"

17
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="orderId"

40274
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="orderStatus"

Ready
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="paymentId"

3
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="paymentAmount"

34.95
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="customerReferenceId"

7
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="referenceId"

11223344
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="referenceText"

I am reference text
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="filename"

Bk-40274-tx17-Mess.pdf
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="fileformat"

pdf
------------d0f32ac86c8249c9aa562c1fcfbfeb66
Content-Disposition: form-data; name="file"; filename="Bk-40274-tx17-Mess.pdf"
Content-Type: application/pdf

<BINARY PDF BYTES REMOVED>

Once you’ve successfully placed a screening order using the screen/backgroundcheck endpoint your order will be issued to the background check team. As your screening order moves through review, messages will be posted to the endpoint you provided in the RequestParamaters postbackUri property.

The message will come in the form of a multipart/form-data POST.

POST Data

The properties provided in the POST message are:

• transactionId – The RentPrep transaction ID for the order
• orderId – The RentPrep screening order ID
• orderStatus – The status of the report [Canceled, Partial, Pending, Ready, Error]
• paymentId – The RentPrep payment ID for the order (if applicable)
• paymentAmount – The payment amount (if applicable)
• customerReferenceId – Your customer reference ID as submitted in your screening request
• referenceId – Your RequestParamaters reference ID as submitted in your screening request
• referenceText - Your RequestParamaters referenceText as submitted in your screening request
• filename – The name of the report file being transmitted
• fileformat – The file type of the report being transmitted [pdf]
• file – The PDF report in binary form

Your endpoint will be posted to many times (usually 5 – 7 times), each time with the updated screening report in PDF form.

An example of the PDF which will be posted back as a byte array can be downloaded here.

Models

BackgroundScreeningOrder

{
    "PackageName": "Platinum",
    "Customer": {
        "CreditCard": {
            "cardNumber": "5419543578415880",
            "cardSecurity": "554",
            "cardType": "mastercard",
            "expireMonth": "09",
            "expireYear": "2020"
        },
        "IPAddress": "127.0.0.1",
        "billingCity": "Buffalo",
        "billingState": "NY",
        "billingStreetAddress": "567 Customer Street",
        "billingZip": "14210",
        "company": "My Company Co.",
        "emailAddress": "jcustomer@email.com",
        "firstName": "John",
        "lastName": "Customer",
        "phone": "9991129999",
        "referenceId": "7"
    },
    "Applicant": {
        "city": "Buffalo",
        "dateOfBirth": "1981-10-12",
        "emailAddress": "",
        "fax": "",
        "firstName": "Hank",
        "lastName": "Mess",
        "middleName": "",
        "phone": "716-204-9999",
        "postalCode": "14210",
        "ssn": "333-22-1111",
        "state": "NY",
        "streetAddress": "567 Some Street"
    },
    "CurrentLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "Employer": {
        "companyName": "Geico",
        "phone": "716-204-9999",
        "supervisorFirstName": "Warren",
        "supervisorLastName": "Buffet"
    },
    "PreviousLandlord": {
        "city": "Buffalo",
        "comments": "",
        "emailAddress": "",
        "fax": "",
        "firstName": "John",
        "lastName": "LandOwner",
        "phone": "716-992-4093",
        "postalCode": "14127",
        "state": "NY",
        "streetAddress": "123 fake street"
    },
    "RequestParameters": {
        "postbackUri": "https://yourpostbackurl.com/postback",
        "postback_password": "",
        "postback_username": "",
        "referenceId": "",
        "referenceText": "",
        "sendCustomerReceipt": false
    }
}

Model Definition

Parameter	Description	Type	Requirements
packageName	The Screening Package you are ordering	ScreeningPackage	Required
Customer	Your customer who is placing the screening order	Customer	Required
Applicant	The Applicant being screened	Applicant	Required
CurrentLandlord	The Applicant’s current landlord	Landlord	Platinum Package Only
PreviousLandlord	The Applicant’s previous landlord	Landlord	Platinum Package Only
Employer	The Applicant’s current employer	Employer	Platinum Package Only
RequestParameters	Additional Request Parameters	RequestParameters	Required

ScreeningPackage

The available Screening Packages which may be ordered

Enum Values

Name	Description
Basic	SSN Verification, Eviction History, Bankruptcies Search, Judgement/Lien Search
Pro	Basic plus U.S. Criminal Search, Sex Offender Search, Homeland Security Search
Platinum	Pro plus Verify Current Residence, Previous Residence, and Employment
CorpWithCredit	U.S. Criminal Search, Eviction History, Transunion Credit Report (with FICO)
CorpCreditOnly	Transunion Credit Report (with FICO)

Customer

{
    "CreditCard": {
        "cardNumber": "5419543578415880",
        "cardSecurity": "554",
        "cardType": "mastercard",
        "expireMonth": "09",
        "expireYear": "2020"
    },
    "IPAddress": "127.0.0.1",
    "billingCity": "Buffalo",
    "billingState": "NY",
    "billingStreetAddress": "567 Customer Street",
    "billingZip": "14210",
    "company": "My Company Co.",
    "emailAddress": "jcustomer@email.com",
    "firstName": "John",
    "lastName": "Customer",
    "phone": "9991129999",
    "referenceId": "7"
}

Personal, billing, and credit card data related to your end user.

Model Definition

Parameter	Description	Type	Requirements
CreditCard	An object containing credit card details for payment	BaseCreditCard	Required unless pre-arranged
firstName	The first name of the end user	string (64)	Required
lastName	The last name of the end user	string (64)	Required
billingStreetAddress	The street address on file with the user’s credit card	string (128)	Required
billingCity	The city on file with the user’s credit card	string (128)	Required
billingState	The state on file with the user’s credit card	string (16)	Required
billingZip	The postal code on file with the user’s credit card	string (32)	Required
company	The business name of the end user	string (64)	Optional
phone	The phone number of the end user	string (24)	Optional
IPAddress	The IP Address of the end user	string (39)	Optional
referenceId	Your internal ID for this end user	string (100)	Optional but should provide
emailAddress	The email address of the end user	string (256)	Required

Applicant

{
    "city": "Buffalo",
    "dateOfBirth": "1981-10-12",
    "emailAddress": "",
    "fax": "",
    "firstName": "Hank",
    "lastName": "Mess",
    "middleName": "",
    "phone": "716-204-9999",
    "postalCode": "14210",
    "ssn": "333-22-1111",
    "state": "NY",
    "streetAddress": "567 Some Street"
}

The personal information of the individual being screened

Model Definition

Parameter	Description	Type	Requirements
firstName	The first name of the applicant	string (32)	Required
lastName	The last name of the applicant	string (64)	Required
middleName	The middle name of the applicant	string (32)	Optional
streetAddress	The street address of the applicant	string (64)	Required
city	The city of the applicant	string (32)	Required
state	The state of the applicant. For domestic addresses use the USPS 2-letter state abbreviation	string (16)	Required
postalCode	The postal code of the applicant	string (32)	Required
phone	The phone number of the applicant	string (24)	Required
ssn	The social security number of the applicant, with hyphens (e.g. 121-72-1111)	string	Required
dateOfBirth	The date of birth of the applicant in the format (yyyy-mm-dd)	date	Required
fax	The fax number of the applicant	string (24)	Optional
emailAddress	The email address of the applicant	string (256)	Optional

Landlord

{
    "city": "Buffalo",
    "comments": "",
    "emailAddress": "",
    "fax": "",
    "firstName": "John",
    "lastName": "LandOwner",
    "phone": "716-992-4093",
    "postalCode": "14127",
    "state": "NY",
    "streetAddress": "123 fake street"
}

The personal information of the applicant’s landlord.

Model Definition

Parameter	Description	Type	Requirements
firstName	The first name of the landlord	string (32)	Required
lastName	The last name of the landlord	string (64)	Required
streetAddress	The street address of the landlord	string (64)	Required
city	The city of the landlord	string (32)	Required
state	The state of the landlord. For domestic addresses use the USPS 2-letter state abbreviation	string (16)	Required
postalCode	The postal code of the landlord	string (32)	Required
phone	The phone number of the landlord	string (24)	Required
fax	The fax number of the landlord	string (24)	Optional
emailAddress	The email address of the landlord	string (256)	Optional
comments	Any comments about the landlord as provided by the applicant	string	Optional

Employer

{
    "companyName": "Geico",
    "phone": "716-204-9999",
    "supervisorFirstName": "Warren",
    "supervisorLastName": "Buffet"
}

Basic information identifying the applicant’s employer and supervisor.

Model Definition

Parameter	Description	Type	Requirements
companyName	The name of the company where the applicant works	string (64)	Required
supervisorFirstName	The first name of the applicant’s supervisor	string (32)	Required
supervisorLastName	The last name of the applicant’s supervisor	string (64)	Required
phone	The phone number of the applicant’s supervisor	string (24)	Required

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 multipart/form-data 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	Required
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

BaseCreditCard

{
    "cardNumber": "5419543578415880",
    "cardSecurity": "554",
    "cardType": "mastercard",
    "expireMonth": "09",
    "expireYear": "2020"
}

The end user’s credit card details for order payment

Model Definition

Parameter	Description	Type	Requirements
cardType	The credit card type	CreditCardType	Required
cardNumber	No hyphens, Numbers only	string (16)	Required
cardSecurity	The card verification value (CVV)	string (5)	Required
expireMonth	The two digit expiration month with leading zero	string (2)	Required
expireYear	The four digit expiration year	string (4)	Required

CreditCardType

The available credit card types for payment

Enum Values

Name	Description
visa	Visa
amex	American Express
discover	Discover
mastercard	Mastercard