Lenders API is a private and secure data service for Canadian lenders.
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.
We will attempt to maintain backwards compatibility when a new version is released. If you wish to upgrade API versions, please contact us.
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.
All requests and responses should be in JSON format. Lenders API will only accept and return the HTTP Content-Type application/json
.
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.
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.
Success.
The request could not be understood by the server due to malformed input.
No valid API key was provided.
The API key does not have the required permissions to perform the requested actions.
The requested resource does not exist
The server has encountered a situation it does not know how to handle.
Any responses that come back with a status code in the 4xx or 5xx ranges will follow a standard error format.
{ "id": "machine-readable", "status": 400, "message": "Human description of the error that occurred." }
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.
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.
PUT
https://www.lendersapi.com/reports/{reference}?immediate={true|false}
PUT https://www.lendersapi.com/reports/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" } } ] }
{ "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 } }
{ "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" } ] } ] }
{ "id": "invalid", "status": 400, "message": "Field 'dob' expected 'YYYY-MM-DD' format." }
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.
GET
https://www.lendersapi.com/reports/{reference}
GET https://www.lendersapi.com/reports/my-loan-5
{ "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 } }
{ "id": "not_found", "status": 404, "message": "No report found." }
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.
GET
https://www.lendersapi.com/reports/{reference}/hits
GET https://www.lendersapi.com/reports/my-loan-5/hits
{ "status": "processing", "reports": [] }
{ "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" } ] } ] }
{ "id": "invalid", "status": 400, "message": "Report 'my-loan-5' not found. Submit the report to search for hits." }
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.
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.
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, }
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.
{ "id": "d608bda0-eaa8-4608-831d-e6d0c9f5d0e2", "type": "report.updated", "testmode": false, "application_name": "application name", "data": { "reference": "loan-id" }, "created": 1589128701 }
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.
POST
https://www.lendersapi.com/reports/backfill
POST https://www.lendersapi.com/reports/backfill
{ "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" } ] } ] }
{ "id": "invalid", "status": 400, "message": "reports should be an array." }
[ { "my-loan-1": { "status": 200 }, "my-loan-2": { "status": 200 } } ]
[ { "my-loan-1": { "status": 200 }, "my-loan-2": { "status": 400, "error": { "id": "invalid", "status": 400, "message": "Field 'status' invalid value 'funded-new'" } } } ]