API Products¶
DLL’s North America Regional APIs can be used to submit finance applications for credit approval, get details of a previously submitted application and make changes to the application. This document is intended to provide an overview of the information necessary for the partner development team to understand the APIs and the various scenarios in which they can be used.
Concepts¶
Programs & Partner Sites¶
(Financial) Program refers to the different types of financing options that can be offered to customers based on defined and negotiated terms in a program agreement. These may include leasing, allowable terms, end of contract options, among others.
Partner Sites (also referred to as Locations) distinguish between multiple physical locations and funding methods. Contacts, both within and outside of DLL, can be assigned at the site level to ensure communications are sent to the applicable interested parties. A Partner can have multiple Sites. Each such Site can have access to multiple Programs.
The North America Regional API suite allows for retrieval of Partner Locations and their associated Programs via the Partner Search and Retrieval APIs.
Financial Products¶
Financial Products refer to the specific financing plans that customers can choose from, such as fixed or variable rate loans or operating leases. The available Financial Products, the details of the corresponding finance structures and pre-configured rates can be obtained from the Program Search and Retrieval APIs.
Assets¶
Assets refer to the specific equipment that is being financed. Assets belong to a Brand, have a Model Number, and are categorized into Master Types and Types. This information can be obtained from the Program Asset Catalog APIs.
Finance Calculations¶
Before submitting a Finance Application, End User can perform Finance Calculations to generate price quotes based on various combinations of Financial Products and related application attributes. These quotes help in getting an estimate of the payment that is to be made based on the parameters provided, before an application is submitted. The quotes can be generated using the Pricing Information and Calculations APIs.
Finance Applications¶
Finance Applications allow End Users to apply for finance, be assessed for creditworthiness and obtain a finance agreement. Consumers are also able to retrieve the current state details for a previously submitted application and are also able to make changes to the application. The submission, retrieval and editing of Finance Applications can be done using the Finance Application APIs.
Scenarios and Flows¶
The following section describes the various scenarios the North America Regional APIs can be used in and the corresponding API workflows.
Scenario 1: Generate Price Quote¶
Generating a Price Quote provides the End User with an estimated payment based on minimal input values. End Users can later convert a quote into a finance quote by adding additional asset details and party information.
API Workflow¶
Get Authorized¶
Before making any API calls, the End User needs to be authorized. The client credentials will be provided by DLL along with the authorization endpoint. The following diagram illustrates the flow for getting authorized
Upon successful authorization, a bearer token will be generated which needs to be retained and used in all subsequent API calls.
Select Finance Program¶
DLL allows Partners to configure multiple Partner Sites based on physical locations and funding requirements. Each of these Sites can have multiple Finance Programs available to them. The Program that is to be used in the current context needs to be identified using the flow illustrated in the following diagram.
Determine Finance Structure¶
The payment parameters of the transaction are determined by the Finance Structure. The Finance Structure can be specified on the basis of a Financial Product as illustrated below.
Alternatively, the Finance Structure can also be explicitly specified by manually entering the values.
Select Assets¶
Minimal asset details need to be provided in order to determine any residual value that would need to be taken into account when generating a quote. The following diagram illustrates the flow for selecting assets.
Note
DLL allows selection of only those assets that exist in DLL’s Asset Catalog.
Generate Price Quote¶
Now that all required information has been obtained, an estimated payment can be determined by generating a Price Quote. The following diagram illustrates the flow for generating a Quote.
Scenario 2: Submit Standard Finance Application¶
A Standard Finance Application provides DLL with all three components necessary to underwrite a transaction and make a credit decision. Those three components are parties, asset, and finance structure. If a Price Quote has already been obtained, the finance structure from the Price Quote can be reused for creating Finance Application. For the purposes of this document, the steps have been repeated.
API Workflow¶
Get Authorized¶
Before making any API calls, the End User needs to be authorized. The client credentials will be provided by DLL along with the authorization endpoint. The following diagram illustrates the flow for getting authorized.
Upon successful authorization, a bearer token will be generated which needs to be retained and used in all subsequent API calls.
Select Finance Program¶
DLL allows Partners to configure multiple Partner Sites based on physical locations and funding requirements. Each of these Sites can have multiple Finance Programs available to them. The Program that is to be used in the current context needs to be identified using the flow illustrated in the following diagram.
Determine Finance Structure¶
The payment parameters of the transaction are determined by the Finance Structure. The Finance Structure can be specified on the basis of a Financial Product as illustrated below.
Alternatively, the Finance Structure can also be explicitly specified by manually entering the values.
Select Assets¶
As DLL is an equipment finance company, details for at least one asset need to be provided when submitting a Standard Finance Application. The following diagram illustrates the flow for selecting assets.
Note
DLL allows selection of only those assets that exist in DLL’s Asset Catalog.
Enter Party Information¶
DLL requires at least the lessee to be specified for a Finance Application. DLL also allows End User to optionally specify additional Parties on the application, like Co-Lessees, Personal Guarantors and Cross-Corporate Guarantors. As of today, DLL does not expose APIs for searching and selecting a Party whose information is already in the database – the Parties need to be manually entered on each Finance Application, as illustrated in the diagram below.
Submit the Finance Application¶
After the Partner Site and Program has been selected, Finance Structure has been determined, Assets have been specified and Parties have been entered, the Finance Application can now be submitted. The following diagram illustrates the flow for submitting the Finance Application.
!!! note Once the Finance Application is submitted successfully, a Finance Application Id will be returned to the End User and the application will be in “assessment” status. This Id is required if, at a later point of time, the End User wants to retrieve the state of the Application or make changes to the Application.
Credit Approval
Most applications move from assessment stage to agreement stage automatically within a couple of minutes of submission. But this is an asynchronous process, so the End User will have to retrieve the application details periodically to determine progress.
-
In some cases, the application needs to be reviewed by a Credit Analyst manually. This manual assessment is completed within a couple of hours.
-
In case additional information is needed from the End User to complete the assessment, it will be completed within couple of hours the information is received.
-
The credit approval has an expiry date, if the application is yet to be booked by the time of this expiry, the application will be withdrawn automatically.
Scenario 3: Get current state details of a Finance Application¶
After the Finance Application has been submitted, it will go through internal processing to assess the creditworthiness, reach a finance agreement, generate relevant documents and eventually conversion to a booked contract. At a later point of time, the End User can get details regarding current state of the application, thereby being informed of the status and also being in-synch if a change has been made internally at DLL.
API Workflow¶
Get Authorized¶
Before making any API calls, the End User needs to be authorized. The client credentials will be provided by DLL along with the authorization endpoint. The following diagram illustrates the flow for getting authorized.
Get Finance Application Details¶
The following diagram illustrates the flow for End User to get the details of a previously submitted Finance Application.
The End User will get the details of the Finance Application along with the current status. The status can be one of the following:
- assessment: The application is still being reviewed for creditworthiness.
- agreement: The credit has been approved.
- withdrawal: The application has been withdrawn, either by DLL due to credit being declined, or by End User through explicit request or inactivity.
- contract: The application is booked and is ready to be funded.
Scenario 4: Edit previously submitted Finance Application¶
After a Finance Application has been credit approved, DLL allows the End User to make changes to the application. But changes are allowed as long as a DLL member is inactively working on the application and a change request is yet to start.
Note
The North America Regional APIs are using RFC 7396 – JSON Merge Patch (https://datatracker.ietf.org/doc/html/rfc7396) as the basis for the PATCH API which is used for submitting changes for a Finance Application.
For Objects and Fields
1. If the End User does not want to make any updates to an existing field or object, the End User should not pass the field or object at all in the PATCH request.
2. If the End User wants to change a field or any field within an object, the updated value should be passed.
3. If the End User wants to remove a field or any field within an object, the End User should pass the value of the field as null.
For Arrays
1. If the End User doesn’t want to make any updates to an existing array, the End User should not pass the array at all in the PATCH request (not even an empty array).
2. If the End User wants to make any updates to any field in an existing array, the End User must send the entire array in its current form. The array sent in the PATCH request will be used to replace the existing data.
- If an empty array (e.g., “assets”:[]) is passed, it is considered as a request to remove all existing data.
API Workflow¶
Get Authorized¶
Before making any API calls, the End User needs to be authorized. The client credentials will be provided by DLL along with the authorization endpoint. The following diagram illustrates the flow for getting authorized.
Get Finance Application Details¶
The following diagram illustrates the flow for End User to get the details of a previously submitted Finance Application.
This will get the End User the latest details on the application (the application could have been updated internally by a DLL member). This will also return the current status of the application. A change can be submitted only if the application is in “agreement” status.
Additional Information Requested¶
If a Finance Application requires Additional Information to be decisioned, then the substatus will be set to "additional-information-requested." A Personal Guarantor or Cross Corporate Guarantor can be submitted.
Edit an Approved Finance Application¶
Changes can be submitted to a Finance Application in "agreement" status. Review the API Specifications to determine which fields can be updated.
Withdraw an Approved Finance Application¶
A Finance Application in "agreement" status can be withdrawn.
Tip
Based on the nature of change (and internal rules defined), the change can be applied immediately or require additional approval.