NAV
C#

Work In Progress

The API documentation is currently a work in progress and will be added to frequently with new code samples and references.

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": "[email protected]",
        "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": "[email protected]",
        "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:

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": "[email protected]",
        "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": "[email protected]",
    "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
C#