Partner Endpoints

Here you'll find documentation on all available endpoints. If you have suggestions on new endpoints you would like to see, please tell us. We would love to hear from you.

Required Parameters

All endpoints require that you provide the following parameters via HTTPS POST:

POST /lenders

The /lenders endpoint will provide a list of all lenders you are authorized for. This endpoint does not require any additional parameters.

Example Request

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/lenders" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response may contain one or more lenders. If no lenders are found, null will be returned.

{
     "name":"Test Mortgage Company",
     "lenderID":"I34TRH7J",
},
{
     "name":"Demo Mortgage Company",
     "lenderID":"OH7JG44T",
},
...

The /lenders endpoint will return the following properties:

POST /lender/users

The /lender/users endpoint will provide a list of all users with the requested role for the requested lender. This endpoint also requires the lenderID and filter parameters as follows:

Example Request

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'lenderID' => "I34TRH7J",
     'filter' => "loanofficer"
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/lender/users" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response may contain one or more users. If no users are found, null will be returned.

{
     "userID":"XBTHT5JZ",
     "firstName":"Tina",
     "lastName":"Jones",
     "phonePrimary":"555-555-5555",
     "email":"tjones@testmortgagecompany.com",
     "role":"Loan Officer",
     "loanOfficer_nmls":"999999",
},
{
     "userID":"28PKXX4A",
     "firstName":"James",
     "lastName":"Carter",
     "phonePrimary":"444-444-4444",
     "email":"jcarter@testmortgagecompany.com",
     "role":"Loan Officer",
     "loanOfficer_nmls":"888888",
},
...

The /lender/users endpoint will return the following properties:

POST /access-token-lender

Getting API Access Tokens

API access tokens are environment-dependent. This means if you are granted an access token in one environment, it can only be used to make API calls in that environment. The Access Token API endpoint is /access-token-lender

Example Request

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'lenderID' => "I34TRH7J",
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/access-token-lender" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

This endpoint requires a lenderID in order to receive an access token. This access token will be needed to make subsequent API calls that affect that lender. Our implementation specialist can give you the appropriate lender public ID value to use. Your integration specialist will also need to enable access to a lender for your partner account.

Response Format

The response will always contain one access token.

{
     "accessToken":"gUS2j4hD6Op2lCtghYJ1gDwH0kms4utaap1knyuw",
     "date":1443566713,
     "expiration":1445726713,
     "ip":"127.0.0.1",
}

You’ll need the accessToken value to make further API calls. This is your API partner access token allowing you to make partner API calls affecting the corresponding lender specified in the payload.

Access Token API Error Structure

If there are errors requesting an API access token, the response will be structured in the following way.

{
     "error":
     {
          "code":403,
          "message":"You are not authorized to access this endpoint."
     }
}

Access Token API Errors

The following is a list of error codes and possible messages depending on the error context.

POST /access-token/destroy

The /access-token/destroy endpoint will completely destroy the requested access token. Once executed, this process cannot be undone.

This endpoint also requires the accessToken parameter as follows:

Example Request

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/access-token/destroy" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response will return null if successful, and return the root key error if not. See Error Codes and Handling.

GET /application

The /application endpoint will create a new session and redirect that session to the application process. This endpoint does not require the apiID and apiKey parameters, but does require the following parameters:

This endpoint expects that boFirstName and boLastName parameters are URL encoded. These values will be URL decoded, and if they are not URL encoded, results may not be as expected.

Example Request

$url = "https://www.besmartee.com/api/partner/application?format=json&accessToken=ACCESS_TOKEN"
     . "&boFirstName=" . urlencode( "Michael Lee" )
     . "&boLastName=" . urlencode( "Smith Jr." )
     . "&boPhone=5555555555";

Response Format

Response will redirect your user to the start of the application process if successful, and return the root key error if not. See Error Codes and Handling.

POST /application/status

The /application/status endpoint will return the application status. This endpoint also requires the accessToken parameter as follows:

Example Request

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/application/status" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response will always contain the last status available.

{
     "statusMain":"New",
     "date":1443569459,
     "user":"Borrower",
     "note":null
}

The /application/status endpoint will return the following properties:

POST /update/user

The /update/user endpoint will update a User borrower. This endpoint also requires the following parameters:

JSON Payload Example

{ "lenderID": "DA4W7MNZ", "userID": "6FD9DD2N", "email": "alice.firstimer@besmartee.com", "user": { "prefEmailNotifications": "0" } }

Below, you'll find details on all required parameters to be included in the JSON payload.

Example Request

$jsonPayload = {...};

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN,
     'data' => $jsonPayload
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/update/user" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response will return null if successful, and return the root key error if not. See Error Codes and Handling.

POST /set-signup-product-pricing

The /set-signup-product-pricing endpoint will return a product and pricing unique identifier that may be used to bypass the loan search and loan product & pricing at the signup page. You must pass in search parameters and the resulting loan product and pricing being applied for. This endpoint requires the following parameters:

JSON Payload Example

{ "borrower" : { "firstName" : "Charles", "lastName" : "Cooper", "dob" : "10/22/1968", "phonePrimary" : "7142458223", "phoneSecondary" : "7142357114", "status" : "Married", "primaryAddressStreet" : "16892 Bolsa Chica St", "primaryAddressCity" : "Huntington Beach", "primaryAddressState" : "CA", "primaryAddressZipcode" : "92649", "email" : "charlescooper@mail.com", "autoCheckTOUPP": 1, "isCreateLeadInPipeline": 1 }, "loan": { "subjectPropertyAddressStreet" : "5361 Bonanza Dr", "subjectPropertyAddressCity" : "Huntington Beach", "subjectPropertyAddressState" : "CA", "subjectPropertyAddressZipcode" : "92649", "loanPurpose": "RefinanceCashOut", "lockPeriod": "30", "homePrice": "500000", "downPayment": "250000", "cashOut": "10000", "fico": "750", "grossMonthlyIncome": "5000.00", "monthlyDebts": "951.62", "propertyType": "SingleFamily", "occupancyType": "PrimaryResidence", "bankruptcy": "0", "foreclosure": "0", "noImpounds": "0", "firstTimeBuyer": "1", "employmentStatus": "FullTime", "documentationType": "Full", "numberHomesOwned": "0", "financeUFMIP": "0", "flip": "0", "streamline": "0", "productProgram": "Conventional", "loanAmortizationType": "AdjustableRate", "loanAmortization": "30", "armType": "7/1", "armIndexMargin": "2.25", "armCapRates": "5/2/5", "lpmi": "0", "hpml": "0", "rate": "4.500", "apr": "4.552", "monthlyPayment": "1315.84", "discountPointPercent": "-1.00", "discountPoint": "-2600.00", "leadID": "ABCD1234", "advertisingCampaignProviderID": "65613", "advertiserID": "4edzbe0c-aa81-4181-a5cf-cef9062a4cea", "loanOfficerUID" : "6ETBTZ4N", "campaignID" : "N4X7UY4N" } }

Below, you'll find details on all required parameters to be included in the JSON payload.

Example Request

$jsonPayload = {...};

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN,
     'data' => $jsonPayload
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/set-signup-product-pricing" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

{"signUpURL":"https://www.besmartee.com/app/signup/p/smartmortgage/r/GEU5229JCL3Z?leadReferralSource=K8ZW5BJM","bsmLeadUID":"K8ZW5BJM"}

Response will return signUpURL and bsmLeadUID if successful, and return the root key error if not. See Error Codes and Handling.

Possible Error Codes & Messages

POST /loan-role-assignment

The /loan-role-assignment endpoint will reassign loan role ( Loan Officer, Loan Officer Assistant, Processors, etc) to loan. This endpoint also requires the following parameters:

JSON Payload Example

{ "leadID": "887", "loanOfficerCRMUID": "DM4W7mNZ" }

Below, you'll find details on all required parameters to be included in the JSON payload.

Example Request

$jsonPayload = {...};

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN,
     'data' => $jsonPayload
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/reassign-loan-officer" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response will return null if successful, and return the root key error if not. See Error Codes and Handling.

POST /create-lead

The /create-lead endpoint will create a lead (or update a lead or loan), which will then pre-populate the consumer and loan officer application experience. This endpoint also requires the following parameters:

JSON Payload Example

{ "losID" : "t5D7HgV3", "loanOfficerUID" : "11DfK59L", "borrowerUID" : "h0HyE55e", "leadURL" : "https://www.salesforce.com/lead", "salesforceOpportunityID" : "0061I00000Ev5dUQAR", "crmLeadID" : "1009103310", "firstName" : "Alice", "lastName" : "Firstimer", "dob" : "01/01/2017", "ssn" : "991919991", "status" : "Unmarried", "phonePrimary" : "7142357114", "email" : "borrower@besmartee.com", "primaryAddressStreet" : "16892 Bolsa Chica St #201", "primaryAddressCity" : "Huntington Beach", "primaryAddressState" : "CA", "primaryAddressZipcode" : "92649", "subjectPropertyAddressStreet" : "1234 Any Street", "subjectPropertyAddressCity" : "Anytown", "subjectPropertyAddressState" : "CA", "subjectPropertyAddressZipcode" : "55555", "homePrice" : 500000, "loanPurpose" : "Purchase", "cashOut": 10000, "propertyType" : "SingleFamily", "productType" : "MortgageLoan", "autoCheckTOUPP" : "0" "leadSource" : "Lending Tree", "referralPersonName" : "Joe Teller", "referralPersonID" : "8Q3nGlf3", "referralBranchName" : "Branch 12-1212", "referralBranchID" : "g9Dv5H74", "campaignPrimaryName" : "New Account Opening Special", "campaignPrimaryID" : "K3t4Bp5F", "offerPrimary" : "", "offerPrimaryPurpose" :"", "offerSecondary" : "", "offerSecondaryPurpose" : "", "segment" : "" }

Below, you'll find details on all parameters that can be included in the JSON payload.

Example Request

$jsonPayload = {...};

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN,
     'data' => $jsonPayload
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/create-lead" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

Response will return a unique publicID, if successful. If a lead is converted into a loan, the publicID will remain unchanged. Response will return the root key error, if any error. See Error Codes and Handling.

{ "publicID": "UU473IOJ" }

POST /get-ppe-anonymous

The /get-ppe-anonymous endpoint takes in search parameters in the query string and returns a list of products, pricing, eligibility and fees from your product & pricing engine (PPE).

JSON Payload Example

{ "channel": "Retail", "subChannel": "Employee", "loanPurpose": [ "RefinanceCashOut" ], "lockPeriod": "30", "zipcode": [ "92649" ], "homePrice": "500000", "downPayment": "250000", "loanAmount": "250000", "cashOut": "10000", "fico": "750", "grossMonthlyIncome": "5000.00", "monthlyDebts": "951.62", "propertyType": "SingleFamily", "numUnits": "1", "buildingStatus": "Existing", "occupancyType": "PrimaryResidence", "bankruptcy": "0", "foreclosure": "0", "noImpounds": "0", "firstTimeBuyer": "1", "employmentStatus": "FullTime", "documentationType": "Full", "numberHomesOwned": "0", "financeUFMIP": "0", "flip": "0", "streamline": "0", "filterARMs": "1", "filterConventional": "1", "filterFHA": "1", "filterVA": "0", "filterHomeReady": "0", "filterUSDA": "0", "filter40Year": "0", "filter30Year": "1", "filter25Year": "0", "filter20Year": "1", "filter15Year": "1", "filter10Year": "1", "filter10YearARM": "1", "filter7YearARM": "1", "filter5YearARM": "1", "filter3YearARM": "0", "filter2YearARM": "0", "filter1YearARM": "0", "filterLess1YearARM": "0", "filterPoints" : { "low" : "-1", "high" : "1" }, "isSecondFinancing": "0", "isStudentLoanCashout": "0", "isTexas50a": "0", "priorLoanIsTexas50a": "0", "ppeID": "173" }

This endpoint can also run a large set of permutations for clients who are looking for bulk pricing, such as a daily nationwide rate card for marketing purposes. You'll need to pass multiple values in the loanPurpose and/or zipcode arrays as such:

{ "loanPurpose": [ "Purchase", "Refinance", "RefinanceCashOut" ], "zipcode": [ "92649", "33154", "10014" ], ... }

Below, you'll find details on all required parameters to be included in the JSON payload.

Example Request

$jsonPayload = {...};

$parameters = array(
     'format' => "json",
     'apiID' => YOUR_API_ID,
     'apiKey' => YOUR_API_KEY,
     'accessToken' => ACCESS_TOKEN,
     'data' => $jsonPayload
);

$curl = curl_init();
curl_setopt( $curl, CURLOPT_URL, "https://www.besmartee.com/api/partner/get-ppe-anonymous" );
curl_setopt( $curl, CURLOPT_POST, count( $parameters ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $parameters );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
$response = curl_exec( $curl );
curl_close( $curl );

print_r( $response );

Response Format

The response will include list of all eligible loan products being requested for with pricing and fees. Response will return the root key error if any error. See Error Codes and Handling.

{ "status": "success", "searchID": "4SG21P", "loanPurpose": "Purchase", "zipcode": "90745", "products": [ { "armFirstAdj": 120, "armFirstAdjCap": 5, "armIndex": "LIBOR", "armIndexMargin": 2.25, "armLifeCap": 5, "armPerAdj": 12, "interestOnly": 0, "loanAmortizationType": "AdjustableRate", "loanTerm": 30, "lpmi": 0, "productName": "10/1 LIBOR ARM", "productProgram": "Conventional", "rates": [ { "apr": 4.672, "fees": [ { "fee": 200, "leSection": "A", "mismoType": "ApplicationFee", "mismoTypeOther": null, "name": "Application Fee", "percent": null }, { "fee": 625, "leSection": "A", "mismoType": "LoanDiscountPoints", "mismoTypeOther": null, "name": "Loan discount points", "percent": null }, { "fee": 500, "leSection": "B", "mismoType": "AppraisalFee", "mismoTypeOther": null, "name": "Appraisal Fee", "percent": null }, { "fee": 40, "leSection": "B", "mismoType": "CreditReportFee", "mismoTypeOther": null, "name": "Credit report", "percent": null }, { "fee": 75, "leSection": "C", "mismoType": "CourierFee", "mismoTypeOther": null, "name": "Title - Courier/Wire Fee", "percent": null }, { "fee": 606, "leSection": "H", "mismoType": "TitleOwnersCoveragePremium", "mismoTypeOther": null, "name": "Title - Owners Title Insurance (optional)", "percent": null } ], "isHPML": 0, "monthlyPayment": 1211.62, "piti": { "principalAndInterest": 486.09, "propertyTaxes": 107.65, "homeownerInsurance": 25.24, "mortgageInsurance": 0 }, "paymentStream": [ { "mortgageInsurance": 0, "numberOfPayments": 120, "principalAndInterest": 1211.63, "startDate": "2018-09-01" }, { "mortgageInsurance": 0, "numberOfPayments": 239, "principalAndInterest": 1198.56, "startDate": "2028-09-01" }, { "mortgageInsurance": 0, "numberOfPayments": 1, "principalAndInterest": 1195.48, "startDate": "2048-08-01" } ], "points": 0.25, "rate": 4.125 }, { "apr": 4.732, "fees": [ { "fee": 200, "leSection": "A", "mismoType": "ApplicationFee", "mismoTypeOther": null, "name": "Application Fee", "percent": null }, { "fee": 500, "leSection": "B", "mismoType": "AppraisalFee", "mismoTypeOther": null, "name": "Appraisal Fee", "percent": null }, { "fee": 40, "leSection": "B", "mismoType": "CreditReportFee", "mismoTypeOther": null, "name": "Credit report", "percent": null }, { "fee": 75, "leSection": "C", "mismoType": "CourierFee", "mismoTypeOther": null, "name": "Title - Courier/Wire Fee", "percent": null }, { "fee": 606, "leSection": "H", "mismoType": "TitleOwnersCoveragePremium", "mismoTypeOther": null, "name": "Title - Owners Title Insurance (optional)", "percent": null } ], "isHPML": 0, "monthlyPayment": 1229.85, "piti": { "principalAndInterest": 486.09, "propertyTaxes": 107.65, "homeownerInsurance": 25.24, "mortgageInsurance": 0 }, "paymentStream": [ { "mortgageInsurance": 0, "numberOfPayments": 120, "principalAndInterest": 1229.85, "startDate": "2018-09-01" }, { "mortgageInsurance": 0, "numberOfPayments": 239, "principalAndInterest": 1203.53, "startDate": "2028-09-01" }, { "mortgageInsurance": 0, "numberOfPayments": 1, "principalAndInterest": 1201.95, "startDate": "2048-08-01" } ], "points": 0, "rate": 4.25 } ] } ], "watchableLoanPrograms": [ "Conventional 10 Year Fixed", "Conventional 15 Year Fixed", "Conventional 30 Year Fixed" ] }

If using optional method to return a set of bulk pricing permutations with parameters loanPurposes and/or zipcodes, then the products array will be wrapped in a new array called permutations as such:

{ "status": "success", "permutations": [ { "searchID": "4SG21P", "loanPurpose": "Purchase", "zipcode": "33154", "products": { "productProgram": "Conventional", "loanTerm": "30", ... }, "watchableLoanPrograms": [ ... ] }, { "searchID": "4SG21P", "loanPurpose": "Purchase", "zipcode": "33154", "products": { "productProgram": "Conventional", "loanTerm": "15", ... }, "watchableLoanPrograms": [ ... ] } ] }

Below, you'll find details on the data types of the response payload.

Possible Error Codes & Messages