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

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 provided by Financeit.
  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

login
string

Required unless anonymous_user is true

password
string

Required unless anonymous_user is true

app_id
required
string

Must be obtained from Financeit

app_secret
required
string

Must be obtained from Financeit

anonymous_user
boolean

If set, login and password don't need to be sent. 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
{
  • "login": "mylogin",
  • "password": "mypassword",
  • "app_id": "valid_app_id",
  • "app_secret": "valid_app_secret"
}

Response samples

Content type
application/json
Example
{
  • "access_token": "f1a9f8da8ab53d3b0ef4caf9ebbe5c77eff91dbe3c674f9cfbc260ae1e8f4c60",
  • "user_id": 12345,
  • "user_type": "Partner"
}

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",
  • "contact_first_name": "Mike",
  • "contact_last_name": "Smith",
  • "contact_position": "owner",
  • "contact_date_of_birth_year": "1960",
  • "contact_date_of_birth_month": "1",
  • "contact_date_of_birth_day": "15",
  • "contact_region_id": "8",
  • "contact_postal_code": "M5S3G2",
  • "referral_uuid": "1A2A3A",
  • "work_phone_1i": "416",
  • "work_phone_2i": "555",
  • "work_phone_3i": "1234",
  • "work_phone_4i": "400",
  • "home_phone_1i": "410",
  • "home_phone_2i": "550",
  • "home_phone_3i": "1230",
  • "home_phone_4i": "400",
  • "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.

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.

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",
  • "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.

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": "Car",
  • "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

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