×

Even Developer Documentation

API Reference

The following endpoints and resources are part of the v1 API. All requests to these endpoints must include a Accept header with the value application/vnd.evenfinancial.v1+json, and most conform to all requirements listed in the API Overview.

Endpoints

POST https://api.evenfinancial.com/leads/rateTables

For submitting a lead and retrieving a rate table of offers. The body of the request must be a valid lead, and the response will be a rate table.

If the POSTed lead is malformed, the endpoint will respond with a 400 Bad Request. Otherwise, it will respond with a 201 Created, and the body will be a new rate table.

GET https://api.evenfinancial.com/originator/rateTables/{UUID}

For retrieving the rate table corresponding to the specified UUID. This should be called when the rate table includes pending originators.

If the if the final segment of the path is not a valid UUID, the endpoint will respond with a 400 Bad Request. If the specified UUID does not exist, it will respond with a 404 Not Found. Otherwise, it will respond with a 200 OK, and the body will be the requested rate table.

Resources

Lead

Information about someone who is interested in a loan, or another financial product. No fields are strictly required in the lead. However, in general, submitting a lead with more data has the potential to result in a rate table with more offers.

{
  "productTypes": ["loan", "savings"],
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "city": "New York",
    "state": "NY",
    "workPhone": "2125551234",
    "primaryPhone": "2125556789",
    "address1": "45 West 21st Street",
    "address2": "5th Floor",
    "zipcode": "10010",
    "monthsAtAddress": 5,
    "driversLicenseNumber": "111222333",
    "driversLicenseState": "NY",
    "ipAddress": "8.8.8.8",
    "activeMilitary": false,
    "militaryVeteran": true,
    "dateOfBirth": "1993-10-09",
    "educationLevel": "bachelors",
    "ssn": "111-22-3333"
  },
  "loanInformation": {
    "purpose": "home_refi",
    "loanAmount": 10000
  },
  "mortgageInformation": {
    "propertyType": "condo",
    "propertyStatus": "own_with_mortgage",
    "propertyValue": 200000,
    "mortgageBalance": 10000,
    "lenderName": "Bank OF NY",
    "hasFHALoan": true,
    "currentWithLoan": true
  },
  "creditCardInformation": {
    "allowAnnualFee": true,
    "cardBenefits": [ "travel_incentives" ]
  },
  "creditInformation": {
    "providedCreditRating": "excellent",
    "providedNumericCreditScore": 750
  },
  "financialInformation": {
    "employmentStatus": "employed",
    "employmentPayFrequency": "weekly",
    "annualIncome": 120000,
    "monthlyNetIncome": 10000,
    "bankName": "Santander",
    "bankRoutingNumber": "231372691",
    "bankAccountType": "savings",
    "monthsAtBank": 10,
    "bankAccountNumber": "1234567890"
  },
  "employmentInformation": {
    "employerName": "EVEN Financial",
    "employerAddress": "45 W 21st St",
    "employerCity": "New York",
    "employerState": "NY",
    "employerZip": "10010",
    "jobTitle": "Software Engineer",
    "monthsEmployed": 14,
    "directDeposit": true,
    "payDate1": "2004-10-06",
    "payDate2": "2004-11-06"
  },
  "legalInformation": {
    "consentsToFcra": true,
    "consentsToTcpa": true,
    "tcpaLanguage": "I agree to be contacted by Even Financial and its partners at the telephone number(s) I have provided above to explore personal loan offers, including contact through automatic dialing systems, artificial or pre-recorded voice messaging, or text message. I understand my consent is not required as a condition to purchasing any goods or services from anyone."
  },
  "clientTags": {
    "hello": [
      "world",
      "there"
    ],
    "something": [
      "else"
    ]
  }
}


Field Details


clientTags

Arbitrary, client-defined values to associate with the lead for the purposes of data segmentation. Must be a JSON object with strings for keys, and arrays of strings for values.


creditCardInformation.cardBenefits

The card benefits a user would like to choose from. Must be one of the following values:

  • balance_transfer
  • earning_rewards
  • improve_credit
  • travel_incentives

creditInformation.providedCreditRating

The credit range that the user’s credit score fall into. Must be one of the following values:

  • excellent (720 and above)
  • good (660 to 719)
  • fair (600 to 659)
  • poor (600 and below)

financialInformation.backAccountType

The type of banking account that the user has. Must be one of the following values:

  • checking
  • savings
  • other

financialInformation.employmentPayFrequency

The schedule according to which the user get’s paid. Must be one of the following values:

  • weekly
  • biweekly
  • twice_monthly
  • monthly

financialInformation.employmentStatus

The user’s current employment status. Must be one of the following values:

  • employed
  • military
  • not_employed
  • other
  • retired
  • self_employed

mortgageInformation.propertyStatus

How the user finances their residence. Must be one of the following values:

  • own_outright
  • own_with_mortgage
  • rent

mortgageInformation.propertyType

The user’s residence type. Must be one of the following values:

  • condo
  • multi_unit
  • rent
  • single_family
  • townhouse

loanInformation.purpose

The reason for the loan, if applicable. Must be one of the following values:

  • auto
  • boat
  • business
  • debt_consolidation
  • green
  • home_improvement
  • household_expenses
  • large_purchases
  • medical_dental
  • moving_relocation
  • other
  • student_loan
  • taxes
  • vacation
  • wedding

personalInformation.educationLevel

The highest educational degree attained by the user. Must be one of the following values:

  • associate
  • bachelors
  • high_school
  • masters
  • other
  • other_grad_degree

productTypes

The types of offers the user wants returned:

  • credit_card
  • loan
  • mortgage
  • savings

Credit Card Offer

A credit card offer from a partner. Included in a rate table in the creditCardOffers array. A credit card offer details is guaranteed to have the following fields: cardImageUrl, maxPurchaseApr, minPurchaseApr, maxCashAdvanceApr, minCashAdvanceApr, maxBalanceTransferApr, minBalanceTransferApr, annualFee.

{
  "uuid": "6e6a6043-afaf-4c61-971b-a035282548f0",
  "partner": {
    "uuid": "f7df60e5-13c0-4241-aba0-61a8877e142f", 
    "name": "Partner Bank", 
    "description": "Partner Bank Description", 
    "disclaimer": "Partner Bank Disclaimer", 
    "imageUrl": "http://dev-admin.evenfinancial.com/partner_image.gif"
  },
  "marketplace": {
    "uuid": "7a95da6d-2a03-4f58-beb0-d31eaddcfb15", 
    "name": "Marketplace", 
    "description": "Source of offers", 
    "disclaimer": "Source disclaimer", 
    "imageUrl": "http://dev-admin.evenfinancial.com/marketplace_image.gif"
  },
  "productType": "credit_card",
  "productSubType": "credit_card",
  "url": "http://dev-offers.evenfinancial.com/ref/6bb3ed5c-f1d1-4c69-af1c-d02a4e028b3c",
  "details": {
    "cardName": "Credit Card",
    "cardImageUrl": "https://example.com/image",
    "cardBenefits": [ "travel_incentives" ],
    "ratesUrl": "https://example.com/",
    "maxPurchaseApr": 15,
    "minPurchaseApr": 15,
    "maxPurchaseIntroApr": 0,
    "minPurchaseIntroApr": 0,
    "purchaseIntroAprTerm": 12,
    "purchaseIntroAprTermUnit": "month",
    "maxCashAdvanceApr": 15,
    "minCashAdvanceApr": 15,
    "maxCashAdvanceIntroApr": 0,
    "minCashAdvanceIntroApr": 0,
    "cashAdvanceIntroAprTerm": 12,
    "cashAdvanceIntroAprTermUnit": "month",
    "maxBalanceTransferApr": 15,
    "minBalanceTransferApr": 15,
    "maxBalanceTransferIntroApr": 0,
    "minBalanceTransferIntroApr": 0,
    "balanceTransferIntroAprTerm": 12,
    "balanceTransferIntroAprTermUnit": "month",
    "annualFee": 100,
    "annualIntroFee": 0,
    "annualIntroFeeTerm": 1,
    "details": [
      "Credit card detail"
    ],
    "additionalDetails": [
      "Possibly hidden credit card detail"
    ]
  }
}

Field Details


maxPurchaseIntroApr
, minPurchaseIntroApr, maxCashAdvanceIntroApr, minCashAdvanceIntroApr, maxBalanceTransferIntroApr, and minBalanceTransferIntroApr

A value of -1 indicates the field does not apply to this offer, and should be displayed as N/A.


purchaseIntroAprTermUnit
, cashAdvanceIntroAprTermUnit, and balanceTransferIntroAprTermUnit

The period of time that purchaseIntroAprTerm, cashAdvanceIntroAprTerm, and balanceTransferIntroAprTerm, respectively, refers to. Must be one of the following values:

  • day
  • month
  • year

annualIntroFeeTerm

Number of years for annualIntroFee.


details

A list of credit card details that must be shown when displaying the offer.


additionalDetails

A list of credit card details that must be shown when displaying the offer, but can be hidden behind an additional user action.

Loan Offer

A loan offer from a originator. Included in a rate table in the loanOffers array. A loan offer is guaranteed to have the following fields: originator, preQualified, preApproved, termLength, termUnit, uuid

{
  "uuid": "fef16e91-960f-4ac7-a8ec-98d7a6b32c7e",
  "originator": <Originator>,
  "originatorId": null,
  "termLength": 36,
  "termUnit": "month",
  "maxAmount": 25000,
  "minAmount": 1500,
  "maxApr": 35.99,
  "minApr": 25.01,
  "meanApr": 30.5,
  "feeRate": null,
  "maxFeeRate": null,
  "minFeeRate": null,
  "feeFixed": null,
  "maxFeeFixed": null,
  "minFeeFixed": null,
  "allowPrepayment": true,
  "prepaymentFee": 0,
  "monthlyPayment": 119.3,
  "maxMonthlyPayment": 137.4,
  "minMonthlyPayment": 119.3,
  "meanMonthlyPayment": 128.18,
  "maxTotalPayment": 4947,
  "minTotalPayment": 4295,
  "meanTotalPayment": 4615,
  "terms": null,
  "url": "http://offers.evenfinancial.com/ref/64c5ff44-983b-4b47-940d-4ce4176c1d6f/fef16e91-960f-4ac7-a8ec-98d7a6b32c7e",
  "preQualified": false,
  "preApproved": false,
  "sponsored": false,
  "recommendationScore": 95
}

Field Details


preApproved

If true and the user selects this offer, there is an 95% that they will be approved.


preQualified

If true and the user selects this offer, there is an 80% that they will be approved.


recommendationScore

A number that aggregates factors such as the appropriateness of the loan offer for the user, the likelihood of the user converting on the loan offer, the value of that conversion, etc. The number applies across loan offers and special offers, meaning that a loan offer can be recommended more highly than a special offer and vice versa.


termUnit

The period of time that termLength refers to. Must be one of the following values:

  • day
  • month
  • year

Mortgage Offer

An offer for a home mortgage. Included in a rate table in the mortgageOffers array. All mortgage offer details fields are guaranteed to be included in a mortgage offer.

{
  "uuid": "05de6bf9-f339-413a-95a4-29a6879d2c89",
  "partner": {
    "uuid": "f7df60e5-13c0-4241-aba0-61a8877e142f", 
    "name": "Partner Bank", 
    "description": "Partner Bank Description", 
    "disclaimer": "Partner Bank Disclaimer", 
    "imageUrl": "http://dev-admin.evenfinancial.com/partner_image.gif"
  },
  "marketplace": {
    "uuid": "7a95da6d-2a03-4f58-beb0-d31eaddcfb15", 
    "name": "Marketplace", 
    "description": "Source of offers", 
    "disclaimer": "Source disclaimer", 
    "imageUrl": "http://dev-admin.evenfinancial.com/marketplace_image.gif"
  },
  "productType": "mortgage",
  "productSubType": "purchase",
  "url": "http://dev-offers.evenfinancial.com/ref/a2d79303-7181-415c-bb19-a561ed5a1960",
  "consumerRating": 1,
  "disclaimer": "Offer disclaimer",
  "details": {
    "interestRate": 3.5,
    "loanType": "five_one_adjustable",
    "priceAdjustment": 0,
    "monthlyPayment": 1316,
    "netClosingCosts": 13678,
    "apr": 3.615,
    "loanTerm": 30,
    "adjustmentType": "par"
  }
}

Field Details


loanType

Indicates the rate type and loan term. Must be one of the following:

  • fifteen_year_fixed
  • thirty_year_fixed
  • five_one_adjustable
  • seven_one_adjustable
  • ten_one_adjustable

adjustmentType

Indicates whether the loan product contains lender credits, lender points, or is close to par value. Must be one of the following:

  • credits
  • par
  • points

Savings Offer

An offer for a savings or money market account

{
    "uuid": "60a32cee-a5aa-4358-a5fe-f8070f8f2a14",
    "partner": {
      "uuid": "f7df60e5-13c0-4241-aba0-61a8877e142f",
      "name": "Partner Bank",
      "description": "Partner Bank Description",
      "disclaimer": "Partner Bank Disclaimer",
      "imageUrl": "http://dev-admin.evenfinancial.com/partner_image.gif"
    },
    "marketplace": {
      "uuid": "7a95da6d-2a03-4f58-beb0-d31eaddcfb15",
      "name": "Marketplace",
      "description": "Source of offers",
      "disclaimer": "Source disclaimer",
      "imageUrl": "http://dev-admin.evenfinancial.com/marketplace_image.gif"
    },
    "productType": "savings",
    "productSubType": "money_market_account",
    "url": "http://dev-offers.evenfinancial.com/ref/1ed2f58e-af3f-409e-a1e6-f7f00f18cd88",
    "consumerRating": 80,
    "details": {
      "name": "Ally Bank",
      "description": "Open an Account Today. Ally Bank, Member FDIC.",
      "details": "",
      "rate": 1.14,
      "annualPercentYield": 1.15,
      "compoundingMethod": "annually",
      "introductoryPeriodMonths": 0,
      "introductoryRate": 0,
      "minimumDeposit": 0,
      "minimumDepositWithFees": 0,
      "monthlyFee": 0,
      "checkWriting": false,
      "effectiveAsOf": 1501113600000
    }
  }

partner

The provider of the offer.


marketplace

The marketplace that the partner’s offers are sourced from.


consumerRating

The rating of the offer out of 100.


compoundingMethod

The way the interest compounds:

  • annually
  • continuous
  • daily
  • monthly
  • quarterly
  • semiAnnually
  • simple
  • weekly

 

Originator

A financial service provider that issues loans. Included in a loan offer as loanOffer, and in a rate table in the pendingOriginators array. An originator is guaranteed to have the following fields:
key, name.

{
  "key": "avant",
  "name": "Avant",
  "description": "Personal loans from $1,000 to $35,000",
  "images": [
    {
      "sizeKey": "150",
      "url": "aff-tag.evenfinancial.com/images/avant/avant_120.png"
    },
    {
      "sizeKey": "115",
      "url": "aff-tag.evenfinancial.com/images/avant/avant_120.png"
    }
  ],
  "disclaimer": "Suspendisse rhoncus magna erat, nec rhoncus leo elementum eget."
}

Rate Table

A listing of financial product offers for a specific lead. Is built asynchronously; pending results are indicated by the pendingOriginators array.

{
  "uuid": "2c6cb6e4-0aa2-4ab5-9109-8679de537e10",
  "leadUuid": "f823a7c0-586a-4fc3-9cfa-c38694b80b2c",
  "pendingOriginators": [<Originator>],
  "loanOffers": [<Loan Offer>],
  "specialOffers": [<Special Offer>]
}

Required Fields

A rate table is guaranteed to have the following fields:
leadUuid, uuid

Field Details


pendingOriginators

If we submitted a request to an originator’s API and are still awaiting a response, the originator record will be included in this array. If there are any pending originators, the rate table should be reloaded via the GET https://api.evenfinancial.com/originator/rateTables/{UUID} endpoint

Special Offer

A special offer is an offer for a financial product other than a consumer loan. A special offer is guaranteed to have the following fields: name, uuid, desc, url, partnerName, partnerImageUrl

{
  "uuid": "6a43bd3d-67ba-4cdf-9fb0-c137b869fb26",
  "name": "Resolve Your Debt",
  "desc": "Apply today for our customized debt resolution solutions and join thousands of other customers on the road to financial freedom.",
  "url": "http://special-offers.evenfinancial.com/ref/74539c71-4558-401b-916c-ae69fc59fc29/6cecafe3-78fb-40b5-9775-41dbb0537ca0",
  "partnerName": "Freedom Debt Relief",
  "partnerImageUrl": "http://aff-tag.evenfinancial.com/images/freedom/debt-relief/fdr.png",
  "recommendationScore": 76
}

Field Details


recommendationScore

A number that aggregates factors such as the appropriateness of the special offer’s product for the user, the likelihood of the user converting on the special offer, the value of that conversion, etc. The number applies across special offers and loans offers, meaning that a special offer can be recommended more highly than a loan offer and vice versa.