API docs by Redocly

FinanceIt API v3.0 Documentation (3.0.0)

Download OpenAPI specification:

Overview

This API provides functionality to create and manage loans on the FinanceIt platform. It is hosted at: https://www.financeit.ca/en/api/v3

A sandbox for testing this API is hosted at https://training.financeit.ca/en/api/v3

Getting Started Resources

Before diving into the API endpoints, we recommend reviewing these integration guides:

Which Authorization Flow Should You Use?

Authorization Code Flow: This flow involves redirecting the user to our authorization endpoint to grant access, then exchanging an authorization code for an access token to act on the user's behalf. It allows our application to associate an end user with the token and is preferred and/or required for more sensitive endpoints.

Client credentials flow: This flow allows a client application to authenticate and obtain access tokens on its own behalf, without involving the end user.

The appropriate flow to implement depends on whether your application is serving a single merchant or a broker with multiple merchants, and the API endpoints you require access to. See the below table for a breakdown of available actions in different scenarios:

Authorization Flow Client Type Calculator Direct Invites Loans Partners Single Access Links
Authorization Code Any Yes Yes Yes Yes Yes
Client Credentials Individual Merchant Yes Yes Yes N/A No
Client Credentials Broker or Multi-location Yes Yes No No No

Authentication

  1. In order to use the API you need to request API access from FinanceIt.
  2. Once granted access you will be provided with two strings: app_id and app_secret.
  3. If you are following the authorization code flow, you will need to follow the API Integration Guide.
  4. If you are using the client credentials/password flow, pass these two values into /accounts/create_user_oauth_token along with either a login and password for a user or an option indicating that the token is for an anonymous user.
  5. If authentication succeeds, the response will contain an access token
  6. Pass this access token into every API call as an "Authorization" header with "Bearer" 'access_token' " in order to perform operations on behalf of the authenticated (or anonymous) user.
  7. If no access_token is passed into an API call or the passed in access_token is invalid, the response will be 401 Unauthorized.

Errors

If an API call fails, the response will contain an "errors" field which points to a list of error strings.

accounts

Authentication

Create authentication token

For client credentials/password flow only

Request Body schema: application/json
required

Obtain an access token

app_id
required
string

Must be obtained from Financeit

app_secret
required
string

Must be obtained from Financeit

anonymous_user
boolean

The returned token will be for an anonymous user who can perform only a small subset of API actions such as partner create or promo_programs index.

Responses

Request samples

Content type
application/json
Example
{
  • "app_id": "valid_app_id",
  • "app_secret": "valid_app_secret"
}

Response samples

Content type
application/json
Example
{
  • "access_token": "f1a9f8da8ab53d3b0ef4caf9ebbe5c77eff91dbe3c674f9cfbc260ae1e8f4c60"
}

partners

Merchant / Partner / Broker related details

Partners for current user

Request list of partners belonging to user.

Responds with array of partner hashes that belong to distributor, broker, multi location business, or lender

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get details of a Partner

Responds with the requested partner.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
path Parameters
id
required
integer <int64>
Example: 12345

ID of partner to return

Responses

Response samples

Content type
application/json
{
  • "id": "12345",
  • "login": "tv_shack",
  • "email": "mike@tvshack.com",
  • "firm_name": "TV Shack Inc.",
  • "state": "approved",
  • "verticals": [
    ],
  • "organization_type": "corporation",
  • "website": "http://www.mybusiness.com",
  • "firm_address": "123 Firm St.",
  • "firm_address_2": "Firm Two",
  • "firm_city": "Toronto",
  • "firm_postal_code": "M4M4M4",
  • "firm_number_years_in_business": "10",
  • "firm_annual_sales_volume": "1M_to_5M",
  • "address": "123 Main St.",
  • "address_2": "Main Two",
  • "unit_number": "100",
  • "city": "Toronto",
  • "province": "ON",
  • "referral_uuid": "1A2A3A",
  • "firm_current_percent_financed": "0"
}

Get commission totals for a partner

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
path Parameters
id
required
integer <int64>
Example: 12345

ID of partner to return

query Parameters
earned_start_date
string
Example: earned_start_date=2013-01-01

The start date for calculating commissions earned. Must have format 'YYYY-MM-DD'. If blank will return all commissions earned.

earned_end_date
string
Example: earned_end_date=2013-01-01

The end date for calculating commissions earned. Must have format 'YYYY-MM-DD'. If blank will return all commissions earned.

Responses

Response samples

Content type
application/json
{
  • "earned": "2000.50",
  • "outstanding": "1500.00"
}

calculator

Loan Quotes and Calculations

Calculate loan options for potential borrower

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
query Parameters
requested_amount
required
number
Examples:
  • requested_amount=10000 - Small loan
  • requested_amount=50000 - Large loan

Amount for the loan request.

vertical_name
string
Enum: "Home Improvement" "Retail" "Power" "Marine" "Recreational Vehicle"

Required if authenticated as an anonymous user or a partner with multiple verticals.

region_code
string
Enum: "AB" "BC" "MB" "NB" "NL" "NS" "NT" "NU" "ON" "PE" "QC" "SK" "YT"

Two letter uppercase code of the province. Required if insurance is set and authenticated as an anonymous user.

payment_frequency
string
Default: "m"
Enum: "m" "f" "w"

Payment frequency. Either 'm' (monthly, default), 'f' (biweekly), or 'w' (weekly).

fee_paid_by
string
Enum: "borrower" "partner"

Either 'borrower' or 'partner'. Defaults to partner's account setting (authenticated as partner) or 'borrower' (authenticated as anonymous user)

insurance
string
Default: "no"
Enum: "yes" "no"

Whether or not the borrower wants payment protection. Either 'no' (default) or 'yes'. If authenticated as an anonymous user, region_code must also be set.

promo_program_id
integer

ID of promo program for the loan. 0 for free program. See PromoPrograms resource

amortization
integer
Examples:
  • amortization=36 - Short amortization
  • amortization=180 - Long amortization

The loan amortization period in months. See PromoPrograms resource for available amortization periods. Will default to the highest possible amortization for a given promo program

partner_id
integer

Needed if logged in as a broker, distributor or multi location business employee and you want to get back an application_link

work_site_quebec
string
Default: "no"
Enum: "yes" "no"

If the work site is in Quebec this is used to retrieve Quebec rates. Either 'yes' or 'no' (default)

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "application_link": "https://www.financeit.ca/s/hGrkMg"
}

direct_invites

Direct to Consumer applications

Send a Financeit Direct application link

Sends a direct application link to the customer via email or SMS.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
Request Body schema: application/json
required
partner_id
integer

Required if logged in as a broker or multi-location business employee.

vertical_name
string
Enum: "Home Improvement" "Retail" "Power" "Marine" "Recreational Vehicle"

Required if the partner has multiple verticals.

product_type_id
integer

ID of the product. Must be a valid ID.

promo_program_id
required
integer

ID of promo program for the loan. 0 for free program.

send_via
required
string
Enum: "email" "sms" "none" "centah"

Method of sending the application link.

mobile_number
string

Required if send_via is 'sms'. Must be in the format '123-456-7890'.

email
string

Required if send_via is 'email'. Must be a valid email address.

first_name
string

Customer's first name.

last_name
string

Customer's last name.

language
string
Enum: "en" "fr"

Language preference. Defaults to English.

requested_amount
number

Purchase amount. No dollar sign or commas.

amortization
number

Loan amortization length. Required if use_max_amortization is false.

use_max_amortization
boolean

Whether or not to default to the maximum possible amortization.

payment_frequency
string
Enum: "m" "f" "w"

Payment frequency. 'm' (monthly), 'f' (biweekly), or 'w' (weekly).

message
string

Message included in the email if send_via is 'email'. Max 255 characters.

quebec
boolean

Indicates whether the loan is for Quebec province. This parameter influences the default promo program selection when no explicit promo_program_id is provided. Quebec loans may have different rates and terms due to provincial regulations. This parameter is related to the work_site_quebec parameter used in the calculator endpoint.

object

Additional parameters passed as key-value pairs.

lead_id

  • needs to be an integer
  • FIT API won't throw an error if you pass non-integer value into lead_id field; however the FIT system will remove all the non-integer values. Therefore we recommend using integer values only.
  • Financeit system has no validation that checks for positive and negative value for lead_id therefore you can pass negative numbers.

redirect_url

  • needs to be a string less than 255 characters

Responses

Request samples

Content type
application/json
Example
{
  • "requested_amount": 5000,
  • "language": "en",
  • "partner_id": "1",
  • "vertical_name": "Home Improvement",
  • "product_type_id": 1,
  • "promo_program_id": "0",
  • "email": "fluffy@fluffydog.com",
  • "send_via": "email",
  • "first_name": "John",
  • "last_name": "Smith",
  • "custom_params": {
    }
}

Response samples

Content type
application/json
{}

loans

Loan Details

Get loans belonging to user

Retrieves loans belonging to the authenticated user, with filtering options.

Sorted by most recent first.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
query Parameters
start
string <date>
Default: "2011-01-01"
Example: start=2013-01-01

The start date for the search in 'YYYY-MM-DD' format.

end
string <date>
Default: "{today}"
Example: end=2013-01-31

The end date for the search in 'YYYY-MM-DD' format.

state
string
Default: "active"
Enum: "all" "active" "pending_or_disbursed" "pending" "ready_for_funding" "disbursed_or_closed" "declined" "aborted"

Filter loans by state.

partner
integer
Example: partner=1

Filter loans by partner ID, used if user is a broker or multi-location business employee.

limit
integer
Default: 20

Maximum number of loans to return. Default is 20.

page
integer
Default: 1

Defines which "page" of loans to return. For example, if the query would return 15 loans and limit is set to 10, setting page to '1' will return the first 10 loans and setting page to '2' will return the final 5 loans. Default is 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get loan details

Retrieves detailed information about a specific loan by its ID.

LOAN APPLICATION STATUSES:

The following table outlines the possible combinations of state, system_declined, and next_step_in_application and their meanings. The status of each application is determined by the combination of these three fields.

state system_declined next_step_in_application Description
prequalified null Pre-qualified - Complete the application The initial application is pre-qualified based on a soft credit check. The applicant must complete the full application to proceed.
pending_documentation null Complete checklist The loan is approved. The applicant needs to complete their documentation checklist.
pending_documentation null Request funds All required documents and approval conditions have been satisfied. It's time to request funds from the customer.
pending_coborrower_income null Affordability - Action required On Hold (High Debt to Income Ratio). The application is paused due to an excessive debt-to-income (DTI) ratio. Action is required from the applicant to proceed.
partially_funded null Funding A portion of the total approved funds has been disbursed. The loan is not yet finalized.
declined null Try adding a co-borrower Soft Decline. The application has been declined but can get approved by adding a qualified co-borrower.
declined true Provide additional details Hard Decline. The application has been definitively declined. There are no further actions the applicant can take.
aborted null None Cancelled. The application has been cancelled or has expired due to inactivity.
disbursed null None Fully Funded. Total loan amount has been disbursed.
closed null None Paid Off. The loan has been fully repaid by the borrower and is now closed.
Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "partner_id": 632,
  • "description": "Home renovations for first two floors",
  • "created_at": "2012-10-02 17:05:11 UTC",
  • "rate": "12.99",
  • "requested_amount": "1234.0",
  • "fee": "99.0",
  • "principal_amount": "1460.78",
  • "amortization": 36,
  • "term": 36,
  • "payment_frequency": "m",
  • "vertical": "Vehicle",
  • "total_payment_amount": "53.14",
  • "first_payment_date": "2012-10-13",
  • "downpayment_amount": "500",
  • "downpayment_source": "cash",
  • "intended_use": "Vehicle",
  • "vehicle_type": "Car",
  • "state": "pending_documentation",
  • "system_declined": null,
  • "coborrower_relation": "spouse",
  • "coborrower_relation_other": "",
  • "max_amount": 40000,
  • "min_amount": 1000,
  • "credit_limit": "30000",
  • "max_amort": 108,
  • "api_notices": [
    ],
  • "lead_id": 123,
  • "expiry_date": "2025-10-5",
  • "commission_insurance_amount": "100.0",
  • "promo_program": {
    },
  • "insurance_premium": {
    },
  • "vehicle": {
    },
  • "vehicles": [
    ],
  • "file_attachments": [
    ],
  • "approval_conditions": [
    ],
  • "funded": false,
  • "next_step_in_application": "Complete Financeit Checklist"
}

Get loan ID by lead ID

Retrieves the loan ID associated with a given lead ID.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
query Parameters
lead_id
required
integer
Example: lead_id=12345

The ID of the lead.

partner_id
integer
Example: partner_id=789

The ID of the partner connected to the lead ID. Required if logged in as a broker, distributor, or multi-location business employee.

Responses

Response samples

Content type
application/json
{
  • "id": 67890
}

promo_programs

Promo Programs

Get available promo programs and amortization periods

Retrieves available promo programs and their amortization periods. This endpoint can be accessed using an anonymous user's access token.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
query Parameters
vertical_name
string
Enum: "Home Improvement" "Retail" "Power" "Marine" "Recreational Vehicle"
Example: vertical_name=Home Improvement

Required if authenticated as an anonymous user or a partner with multiple verticals.

partner_id
integer

Required if logged in as a broker or multi-location business employee.

loan_id
integer

Loan ID to base the response on.

Responses

Response samples

Content type
application/json
{
  • "promo_programs": [
    ]
}

subverticals

Subverticals

SUBVERTICALS AND PRODUCT TYPE:
vertical_name subvertical_id subvertical_name product_types_id product_types_name
Home Improvement 1 heating_cooling_and_water 1 air_conditioner
Home Improvement 1 heating_cooling_and_water 2 air_filtration_purification
Home Improvement 1 heating_cooling_and_water 3 furnace
Home Improvement 1 heating_cooling_and_water 4 fireplace
Home Improvement 1 heating_cooling_and_water 5 boiler_replacement
Home Improvement 1 heating_cooling_and_water 6 water_heater
Home Improvement 1 heating_cooling_and_water 7 water_softening
Home Improvement 1 heating_cooling_and_water 8 water_filtration_purification
Home Improvement 1 heating_cooling_and_water 9 other
Home Improvement 2 pool_and_spa 101 hot_tub
Home Improvement 2 pool_and_spa 102 swim_spa
Home Improvement 2 pool_and_spa 103 in_ground_pool
Home Improvement 2 pool_and_spa 104 above_ground_pool
Home Improvement 2 pool_and_spa 105 pool_repair_and_renovation
Home Improvement 2 pool_and_spa 106 pool_equipment
Home Improvement 2 pool_and_spa 107 sauna
Home Improvement 2 pool_and_spa 108 other
Home Improvement 3 interior_improvement 201 electrical
Home Improvement 3 interior_improvement 202 flooring
Home Improvement 3 interior_improvement 203 painting
Home Improvement 3 interior_improvement 204 plumbing
Home Improvement 3 interior_improvement 205 kitchen_renovation
Home Improvement 3 interior_improvement 206 bathroom_renovation
Home Improvement 3 interior_improvement 207 basement_renovation
Home Improvement 3 interior_improvement 208 living_space_renovation
Home Improvement 3 interior_improvement 209 staircase_remodel
Home Improvement 3 interior_improvement 210 insulation
Home Improvement 3 interior_improvement 211 window_fashions
Home Improvement 3 interior_improvement 212 other
Home Improvement 4 exterior_improvement 301 windows_and_doors
Home Improvement 4 exterior_improvement 302 roofing
Home Improvement 4 exterior_improvement 303 eavestroughs_and_gutters
Home Improvement 4 exterior_improvement 304 garages
Home Improvement 4 exterior_improvement 305 siding_panelling
Home Improvement 4 exterior_improvement 306 landscaping
Home Improvement 4 exterior_improvement 307 deck_and_fence
Home Improvement 4 exterior_improvement 308 home_addition
Home Improvement 4 exterior_improvement 309 solar
Home Improvement 4 exterior_improvement 310 other
Home Improvement 5 retail 401 indoor_products
Home Improvement 5 retail 402 outdoor_products
Home Improvement 5 retail 403 sporting_goods_and_recreation
Home Improvement 5 retail 404 service_and_repair
Home Improvement 5 retail 405 electronic_goods
Home Improvement 5 retail 406 security_systems
Home Improvement 5 retail 407 outbuildings_sheds
Home Improvement 5 retail 408 other

Get available subverticals and product types

Retrieves available subverticals and their product types.

This endpoint can be accessed using an anonymous user's access token.

Authorizations:
oAuth2PasswordoAuth2AuthorizationCode
query Parameters
vertical_name
string
Enum: "Home Improvement" "Retail" "Power" "Marine" "Recreational Vehicle"
Example: vertical_name=Home Improvement

Required if authenticated as an anonymous user or a partner with multiple verticals.

partner_id
integer

Required if logged in as a broker or multi-location business employee.

Responses

Response samples

Content type
application/json
{
  • "subverticals": [
    ]
}

Create a special link to give single loan access to the employee with the passed in email.

Authorizations:
oAuth2AuthorizationCode
Request Body schema: application/json
required
loan_id
required
integer

ID of the loan

Responses

Request samples

Content type
application/json
{
  • "loan_id": 12345
}

Create a special link to give loan creation access to the partner employee with the passed in email.

Authorizations:
oAuth2AuthorizationCode
Request Body schema: application/json
required
partner_id
integer

ID of the partner (required if logged in as a broker, distributor, or multi-location business employee)

lead_id
required
integer

ID of the lead

email
string

email of the partner employee associated to the customized link.

object

custom parameters for the loan quotation

object

Hash containing details for borrower who will apply for loan using this link

Array of objects

Array of Hashes indicating all individuals who should recieve an email about loans created using this link

Responses

Request samples

Content type
application/json
{
  • "lead_id": 12345,
  • "partner_id": 768,
  • "custom_params": {
    },
  • "borrower": {
    },
  • "contacts": [
    ]
}

Response samples