API Documentation

Lenders API is a private and secure data service for Canadian lenders.

Overview

Welcome to the Lenders API docs. The service allows participating lenders to better identify suspicious activity and improve underwriting. We offer a standard HTTP JSON REST API.

Backwards Compatibility

We will attempt to maintain backwards compatibility when a new version is released. If you wish to upgrade API versions, please contact us.

Authentication

You should have received your Username, Live API Key, and Test API Key to authenticate requests. Lenders API requires HTTP Basic Authentication with your Username as the username and API Key as the password. Test mode works the same as live mode, except your data is completely separate.

Content-Type

All requests and responses should be in JSON format. Lenders API will only accept and return the HTTP Content-Type application/json.

Date Format

All date fields must be provided in YYYY-MM-DD format. It is possible to partially specify any date field. For example: "2020", "2020-01", or "2020-01-05" are all valid values.

HTTP Status Code

Lenders API uses HTTP status codes to indicate success or failure. Status codes in the 2xx range indicate success. Status codes in the 4xx range indicate the client is responsible for the error, such as missing fields. Status codes in the 5xx range indicate the server is responsible for the error.

HTTP Status Codes
200 - OK

Success.

400 - Bad Input

The request could not be understood by the server due to malformed input.

401 - Unauthorized

No valid API key was provided.

403 - Forbidden

The API key does not have the required permissions to perform the requested actions.

404 - Not Found

The requested resource does not exist

500 - Server Error

The server has encountered a situation it does not know how to handle.

Errors

Any responses that come back with a status code in the 4xx or 5xx ranges will follow a standard error format.

Error Response
{
  "id": "machine-readable",
  "status": 400,
  "message": "Human description of the error that occurred."
}

API Endpoints

The reporting schema is flexible and most fields are optional. To keep your information secure, we only return matching information from matching reports. You can safely submit all relevant information.

Submit Report

The endpoint to create or update a report. The {reference} must be a unique value associated with the loan or application within your company. Report each entity or individual that is a party to the loan or the loan application as a separate array entry. Business reporting will often include one entity and multiple individuals.

If a report with the same reference value already exists under your account, the database is updated with the newly submitted data.

Processing the Report

By default the reports are processed in an asynchronous manner. When the request is submitted, the endpoint acknowledges the request and the report is queued for computing matches via a background job. The result can later be obtained using the search hits endpoint.

Immediate Matching

The endpoint supports also an optional query parameter immediate. If immediate is set to true, the result is immediately computed and returned. The response is same as that of search hits endpoint.

This mode is useful if your workflow requires realtime matching reports for the data you submit.

HTTP Endpoint
PUThttps://www.lendersapi.com/reports/{reference}?immediate={true|false}
Request Body
object
status string
Application status at the time of sending in the report.
"submitted", "rejected", "funded", "withdrawn", "paid-in-full", "charged-off"
loan object
amount_requested number
Amount that the borrower requests from the lender in their application.
amount_funded number
Amount that the borrower receives from the lender.
currency_code string
Currency of the loan. ISO 4217 format.
flags array
string
Flags for borrower behaviours, Multiple are allowed.
"identity-theft", "identity-fraud", "washing-transactions", "rerouting-sales", "consumer-proposal", "personal-bankruptcy", "incorporated-bankruptcy", "document-tampering", "misrepresentation-of-business-ownership", "sells-business-without-notifying-lender", "first-payment-default", "misrepresents-services", "misrepresents-loan-product", "failure-to-deliver-services", "illegal-or-abusive-sales-practices", "mishandling-borrower-data"
entities array
List of entities
object
role * string
Entity role in the report.
"merchant-borrower", "merchant-partner"
entity_name string
Legal business name
dba string
Doing business as trade name
entity_type string
Legal types in Canada.
"corporation", "partnership", "sole-proprietorship", "cooperative"
entity_number string
Employer identification number or tax number
naics_code string
Industry code for business
established string
Date legally established. Should be in YYYY-MM-DD format.
addresses array
List of associated addresses.
address object
type string
Label for the address.
"office", "home", "mailing", "other"
address * string
Full address (line breaks allowed).
links array
List of associated links.
link object
type string
An optional label for the link. Should be 'website' for now.
"website"
url * string
HTTPS or HTTP URL of the website.
emails array
List of associated emails.
email object
type string
An optional label for email.
"support", "other"
email * string
Full email address.
phones array
List of associated phone numbers.
phone object
type string
An optional label for the phone.
"fax", "office", "home", "work", "personal", "other"
phone * string
Full phone number (country code and extension allowed).
individuals array
List of individuals.
object
role * string
Individual's role in the report.
"consumer-borrower", "merchant-partner-rep", "merchant-borrower-rep"
legal_name string
Full legal name
dob string
Date of birth. Should be in YYYY-MM-DD format.
addresses array
List of associated addresses.
address object
type string
Label for the address.
"office", "home", "mailing", "other"
address * string
Full address (line breaks allowed).
links array
List of associated links.
link object
type string
An optional label for the link. Should be 'website' for now.
"website"
url * string
HTTPS or HTTP URL of the website.
emails array
List of associated emails.
email object
type string
An optional label for email.
"work", "personal", "other"
email * string
Full email address.
phones array
List of associated phone numbers.
phone object
type string
An optional label for the phone.
"fax", "office", "home", "work", "personal", "other"
phone * string
Full phone number (country code and extension allowed).
sin string
Social insurance number
drivers_license object
Optional
number * string
Unique Drivers License number
expired string
Expiry date. Should be in YYYY-MM-DD format.
province string
2-letter alpha province code. Required if country is CA or empty.
country string
2-letter alpha country code. Will default to CA if not provided.
omvic_registration_certificate object
Optional
registration_number * string
The registration or license number.
name string
The name of the individual as printed on the certificate.
expired string
The expiry date of the certificate in YYYY-MM-DD format.
dealer_registration_number string
The registration or license number of the dealership.
dealer_name string
The name of the dealership as printed on the certificate.
passport object
Optional
number * string
Unique Passport number
issued string
Issued date. Should be in YYYY-MM-DD format.
expired string
Expiry date. Should be in YYYY-MM-DD format.
country string
2-letter alpha country code. Will default to CA if not provided.
devices array
List of devices
object
ip_address string
IP address of the user/device. Both IPv4 and IPv6 are accepted.
user_agent string
Obtained from User-Agent request header or navigator.userAgent browser property.
language string
Obtained from Accept-Language request header or navigator.language browser property.
device_memory number
Obtained from Device-Memory request header or navigator.deviceMemory browser property.
cpu_class string
navigator.cpuClass browser property.
color_depth number
window.screen.colorDepth browser property.
pixel_ratio number
window.devicePixelRatio browser property.
touch_support boolean
Boolean flag indicating if the device is touch supported.
timezone_offset number
Timezone offset as the time zone difference, in minutes, from current locale (host system settings) to UTC. Obtained using `Date.prototype.getTimezoneOffset()` from device browser.
do_not_track boolean
Request header indicating the user's tracking preference
Request

PUT   https://www.lendersapi.com/reports/my-loan-5

Request Body
{
  "status": "rejected",
  "flags": [
    "identity-theft"
  ],
  "entities": [
    {
      "role": "merchant-borrower",
      "entity_name": "ABC Inc",
      "dba": "Super Yachts",
      "entity_type": "corporation",
      "entity_number": "999999999",
      "naics_code": "72341",
      "addresses": [
        {
          "type": "other",
          "address": "142 Bruton St Port Hope ON L1A 1V5"
        }
      ],
      "established": "2019-05"
    }
  ],
  "individuals": [
    {
      "role": "merchant-borrower-rep",
      "legal_name": "Mitchel P Chernoff",
      "dob": "1962-06-18",
      "addresses": [
        {
          "type": "home",
          "address": "715 15th St , Castlegar, BC, V1N 2K8"
        }
      ],
      "emails": [
        {
          "type": "work",
          "email": "mitchel@abc.xyz"
        }
      ],
      "phones": [
        {
          "type": "work",
          "phone": "555-555-5555"
        }
      ],
      "sin": "046-45-4286",
      "drivers_license": {
        "number": "555555555555",
        "expired": "2022-01"
      },
      "passport": {
        "number": "555555555555",
        "issued": "2015",
        "expired": "2025"
      }
    }
  ]
}
Success Response (async - immediate is not set)
{
  "report": {
    "reference": "my-loan-5",
    "status": "rejected",
    "flags": [
      "identity-theft"
    ],
    "entities": [
      {
        "role": "merchant-borrower",
        "entity_name": "ABC Inc",
        "dba": "Super Yachts",
        "entity_type": "corporation",
        "entity_number": "999999999",
        "naics_code": "72341",
        "addresses": [
          {
            "type": "other",
            "address": "142 Bruton St Port Hope ON L1A 1V5"
          }
        ],
        "established": "2019-05"
      }
    ],
    "individuals": [
      {
        "role": "merchant-borrower-rep",
        "legal_name": "Mitchel P Chernoff",
        "dob": "1962-06-18",
        "addresses": [
          {
            "type": "home",
            "address": "715 15th St , Castlegar, BC, V1N 2K8"
          }
        ],
        "emails": [
          {
            "type": "work",
            "email": "mitchel@abc.xyz"
          }
        ],
        "phones": [
          {
            "type": "work",
            "phone": "555-555-5555"
          }
        ],
        "sin": "046-45-4286",
        "drivers_license": {
          "number": "555555555555",
          "expired": "2022-01"
        },
        "passport": {
          "number": "555555555555",
          "issued": "2015",
          "expired": "2025"
        }
      }
    ],
    "reported": 1589128701
  }
}
Success Response (sync - immediate is set)
{
  "status": "processed",
  "reports": [
    {
      "id": "4b42ae10f607640634773dcc04ef11b",
      "reported": 1589128701,
      "status": "rejected",
      "flags": [
        "identity-theft"
      ],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "ABC Inc",
          "entity_type": "corporation",
          "entity_number": "999999999",
          "naics_code": "72341"
        }
      ],
      "individuals": [
        {
          "role": "merchant-borrower-rep",
          "legal_name": "Mitchel P Chernoff",
          "sin": "046-45-4286"
        }
      ]
    },
    {
      "id": "213cc939c79803dbb327cbf301bf48",
      "reported": 1589128701,
      "status": "funded",
      "flags": [
        "first-payment-default"
      ],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "ABC Inc",
          "entity_type": "corporation",
          "entity_number": "999999999",
          "naics_code": "72341"
        }
      ]
    }
  ]
}
Error Response
{
  "id": "invalid",
  "status": 400,
  "message": "Field 'dob' expected 'YYYY-MM-DD' format."
}

View Report

View a submitted report within your account. Make the request using the same unique {reference} value used in the create/update request to view the submitted report.

HTTP Endpoint
GEThttps://www.lendersapi.com/reports/{reference}
Request

GET    https://www.lendersapi.com/reports/my-loan-5

Success Response
{
  "report": {
    "reference": "my-loan-5",
    "status": "rejected",
    "flags": [
      "identity-theft"
    ],
    "entities": [
      {
        "role": "merchant-borrower",
        "entity_name": "ABC Inc",
        "dba": "Super Yachts",
        "entity_type": "corporation",
        "entity_number": "999999999",
        "naics_code": "72341",
        "addresses": [
          {
            "type": "other",
            "address": "142 Bruton St Port Hope ON L1A 1V5"
          }
        ],
        "established": "2019-05"
      }
    ],
    "individuals": [
      {
        "role": "merchant-borrower-rep",
        "legal_name": "Mitchel P Chernoff",
        "dob": "1962-06-18",
        "addresses": [
          {
            "type": "home",
            "address": "715 15th St , Castlegar, BC, V1N 2K8"
          }
        ],
        "emails": [
          {
            "type": "work",
            "email": "mitchel@abc.xyz"
          }
        ],
        "phones": [
          {
            "type": "work",
            "phone": "555-555-5555"
          }
        ],
        "sin": "046-45-4286",
        "drivers_license": {
          "number": "555555555555",
          "expired": "2022-01"
        },
        "passport": {
          "number": "555555555555",
          "issued": "2015",
          "expired": "2025"
        }
      }
    ],
    "reported": 1589128701
  }
}
Error Response
{
  "id": "not_found",
  "status": 404,
  "message": "No report found."
}

Search Hits

View matching reports across organization boundaries. This endpoint is useful to find reports submitted by other organizations that match one or more entities or individuals in your report. The matching results are sorted with the most recently updated ones at the top.

When a new report is submitted, the matching will start immediately via a background process and could take anywhere from few milliseconds to several seconds. The status of the matching job can be known by checking the status flag in the response. After submitting the report, the flag will be set as processing and will transition to processed when the matching job is completed. If any matches are found when the job completes, the reports array will be populated with the matching reports as shown in the example.

Lenders API will only include matching information using a masking technique. For example, if the social insurance number matches but the email address does not match, the hit will only include the social insurance number as if the other report did not include any email address. It is designed to limit the spread of personal information.

You can also configure webhooks for your account to get a notification when a report is submitted by another organization that matches one of your reports.

HTTP Endpoint
GEThttps://www.lendersapi.com/reports/{reference}/hits
Request

GET    https://www.lendersapi.com/reports/my-loan-5/hits

Success Response (processing)
{
  "status": "processing",
  "reports": []
}
Success Response (processed)
{
  "status": "processed",
  "reports": [
    {
      "id": "4b42ae10f607640634773dcc04ef11b",
      "reported": 1589128701,
      "status": "rejected",
      "flags": [
        "identity-theft"
      ],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "ABC Inc",
          "entity_type": "corporation",
          "entity_number": "999999999",
          "naics_code": "72341"
        }
      ],
      "individuals": [
        {
          "role": "merchant-borrower-rep",
          "legal_name": "Mitchel P Chernoff",
          "sin": "046-45-4286"
        }
      ]
    },
    {
      "id": "213cc939c79803dbb327cbf301bf48",
      "reported": 1589128701,
      "status": "funded",
      "flags": [
        "first-payment-default"
      ],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "ABC Inc",
          "entity_type": "corporation",
          "entity_number": "999999999",
          "naics_code": "72341"
        }
      ]
    }
  ]
}
Error Response
{
  "id": "invalid",
  "status": 400,
  "message": "Report 'my-loan-5' not found. Submit the report to search for hits."
}

Webhooks

Lenders API will notify your backend service about new activity on any of your existing reports. In live mode it will trigger when other Lenders API users submit matching information. In test mode it will trigger when you submit matching information.

Configuring Webhook

Configure your HTTPS endpoint to receive webhook events. Lenders API will send a POST request with Content-Type set to application/json and User-Agent set to LendersAPI/2020-04-10. You may specify additional HTTP headers for authorization or internal use.

To sign up for Lenders API webhooks, please get in touch with tal@lendersapi.com.

Payload Schema
object
id string
A unique id for the event
type string
Type of event
"report.updated"
testmode boolean
Flag to denote if the event is from a test account.
application_name string
Application name provided when setting up the webhook.
data object
reference string
Reference of the report that has new activity.
created number
The time when the event is triggered. Unix epoch format in seconds.
Sample Request
POST /data/lenders-api-callback
Host: yourwebsite.com:443
X-OurCompany-AccessKey: xxxxx
User-Agent: LendersAPI/2020-04-10
Content-Type: application/json
Content-Length: 181
{
    "id": "d608bda0-eaa8-4608-831d-e6d0c9f5d0e2",
    "type": "report.updated",
    "testmode": false,
    "application_name": "application name",
    "data": {
        "reference": "loan-id",
    },
    "created": 1589128701,
}

Update Event

report.updated event is triggered when another lender submits a report that either matched one or more values or caused the removal of one or more previous matches. In test mode, the webhook gets triggered for matches or removal of matches within your account.

Sample Payload
{
  "id": "d608bda0-eaa8-4608-831d-e6d0c9f5d0e2",
  "type": "report.updated",
  "testmode": false,
  "application_name": "application name",
  "data": {
    "reference": "loan-id"
  },
  "created": 1589128701
}

Importing Data

Backfill API

You can import historical records using this endpoint. Importing historical data will improve the accuracy of the search results for all users of Lenders API. The endpoint will accept POST requests with up to 200 records in a single call.

HTTP Endpoint
POSThttps://www.lendersapi.com/reports/backfill
Request Body
object
reports array
object
reference * string
A unique reference or id of the report. The reference should be unique within your organization.
created * number
The time when the report was created in your records. Unix epoch format in seconds.
updated number
The time when the report was updated in your records. Unix epoch format in seconds.
status string
Application status at the time of sending in the report.
"submitted", "rejected", "funded", "withdrawn", "paid-in-full", "charged-off"
loan object
amount_requested number
Amount that the borrower requests from the lender in their application.
amount_funded number
Amount that the borrower receives from the lender.
currency_code string
Currency of the loan. ISO 4217 format.
flags array
string
Flags for borrower behaviours, Multiple are allowed.
"identity-theft", "identity-fraud", "washing-transactions", "rerouting-sales", "consumer-proposal", "personal-bankruptcy", "incorporated-bankruptcy", "document-tampering", "misrepresentation-of-business-ownership", "sells-business-without-notifying-lender", "first-payment-default", "misrepresents-services", "misrepresents-loan-product", "failure-to-deliver-services", "illegal-or-abusive-sales-practices", "mishandling-borrower-data"
entities array
List of entities
object
role * string
Entity role in the report.
"merchant-borrower", "merchant-partner"
entity_name string
Legal business name
dba string
Doing business as trade name
entity_type string
Legal types in Canada.
"corporation", "partnership", "sole-proprietorship", "cooperative"
entity_number string
Employer identification number or tax number
naics_code string
Industry code for business
established string
Date legally established. Should be in YYYY-MM-DD format.
addresses array
List of associated addresses.
address object
type string
Label for the address.
"office", "home", "mailing", "other"
address * string
Full address (line breaks allowed).
links array
List of associated links.
link object
type string
An optional label for the link. Should be 'website' for now.
"website"
url * string
HTTPS or HTTP URL of the website.
emails array
List of associated emails.
email object
type string
An optional label for email.
"support", "other"
email * string
Full email address.
phones array
List of associated phone numbers.
phone object
type string
An optional label for the phone.
"fax", "office", "home", "work", "personal", "other"
phone * string
Full phone number (country code and extension allowed).
individuals array
List of individuals.
object
role * string
Individual's role in the report.
"consumer-borrower", "merchant-partner-rep", "merchant-borrower-rep"
legal_name string
Full legal name
dob string
Date of birth. Should be in YYYY-MM-DD format.
addresses array
List of associated addresses.
address object
type string
Label for the address.
"office", "home", "mailing", "other"
address * string
Full address (line breaks allowed).
links array
List of associated links.
link object
type string
An optional label for the link. Should be 'website' for now.
"website"
url * string
HTTPS or HTTP URL of the website.
emails array
List of associated emails.
email object
type string
An optional label for email.
"work", "personal", "other"
email * string
Full email address.
phones array
List of associated phone numbers.
phone object
type string
An optional label for the phone.
"fax", "office", "home", "work", "personal", "other"
phone * string
Full phone number (country code and extension allowed).
sin string
Social insurance number
drivers_license object
Optional
number * string
Unique Drivers License number
expired string
Expiry date. Should be in YYYY-MM-DD format.
province string
2-letter alpha province code. Required if country is CA or empty.
country string
2-letter alpha country code. Will default to CA if not provided.
omvic_registration_certificate object
Optional
registration_number * string
The registration or license number.
name string
The name of the individual as printed on the certificate.
expired string
The expiry date of the certificate in YYYY-MM-DD format.
dealer_registration_number string
The registration or license number of the dealership.
dealer_name string
The name of the dealership as printed on the certificate.
passport object
Optional
number * string
Unique Passport number
issued string
Issued date. Should be in YYYY-MM-DD format.
expired string
Expiry date. Should be in YYYY-MM-DD format.
country string
2-letter alpha country code. Will default to CA if not provided.
devices array
List of devices
object
ip_address string
IP address of the user/device. Both IPv4 and IPv6 are accepted.
user_agent string
Obtained from User-Agent request header or navigator.userAgent browser property.
language string
Obtained from Accept-Language request header or navigator.language browser property.
device_memory number
Obtained from Device-Memory request header or navigator.deviceMemory browser property.
cpu_class string
navigator.cpuClass browser property.
color_depth number
window.screen.colorDepth browser property.
pixel_ratio number
window.devicePixelRatio browser property.
touch_support boolean
Boolean flag indicating if the device is touch supported.
timezone_offset number
Timezone offset as the time zone difference, in minutes, from current locale (host system settings) to UTC. Obtained using `Date.prototype.getTimezoneOffset()` from device browser.
do_not_track boolean
Request header indicating the user's tracking preference
Request

POST    https://www.lendersapi.com/reports/backfill

Request Body
{
  "reports": [
    {
      "reference": "my-loan-5",
      "created": 1589874475,
      "updated": 1589874475,
      "status": "rejected",
      "flags": [
        "identity-theft"
      ],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "ABC Inc",
          "dba": "Super Yachts",
          "entity_type": "corporation",
          "entity_number": "999999999"
        }
      ],
      "individuals": [
        {
          "role": "merchant-borrower-rep",
          "legal_name": "Mitchel P Chernoff",
          "dob": "1962-06-18"
        }
      ]
    },
    {
      "reference": "my-loan-3",
      "created": 1589874475,
      "updated": 1589874475,
      "status": "approved",
      "flags": [],
      "entities": [
        {
          "role": "merchant-borrower",
          "entity_name": "Alchemy Inc",
          "dba": "Alchemy Chemicals",
          "entity_type": "corporation",
          "entity_number": "999999999"
        }
      ],
      "individuals": [
        {
          "role": "merchant-borrower-rep",
          "legal_name": "Abraham Abid",
          "dob": "1979-03-21"
        }
      ]
    }
  ]
}
Error Response
{
  "id": "invalid",
  "status": 400,
  "message": "reports should be an array."
}
Success Response
[
  {
    "my-loan-1": {
      "status": 200
    },
    "my-loan-2": {
      "status": 200
    }
  }
]
Partial Success Response
[
  {
    "my-loan-1": {
      "status": 200
    },
    "my-loan-2": {
      "status": 400,
      "error": {
        "id": "invalid",
        "status": 400,
        "message": "Field 'status' invalid value 'funded-new'"
      }
    }
  }
]