PLL API Documentation

## Sections
• [API Integration Guide for the PLL Platform](https://doclab.privatelenderlaw.ai/introduction.md): The API Integration Guide for the PLL Platform offers a comprehensive overview of the PLL API, aimed at facilitating seamless interactions between client systems and the PLL platform. Users can leverage this guide to streamline the management of loan document submissions and related processes, accessing an efficient and user-friendly interface for integration purposes. Key Features and Operations Submit Requests Initiate and submit loan document requests with all necessary information. Retrieve Request Status Easily monitor the progress of submitted requests through status checks. Resubmit Requests Resubmit requests with updated information when corrections are required. Manage Comments Post new comments and access existing ones linked to specific requests, improving communication and documentation. Real-Time Notifications Stay updated with real-time changes and updates through Server-Sent Events (SSE) , ensuring prompt client system notifications for any alterations. Guide Overview This guide covers: API Setup : Details on what is reqquired to setup the API in a development environment. API Endpoints : Details on available endpoints for various operations. Request/Response Formats : Comprehensive examples and explanations for smooth integration. While the API’s core functionality is stable, ongoing improvements may lead to minor changes (10-20%) to enhance performance and user experience. This introduction sets the foundation for understanding the purpose and capabilities of the PLL API, ensuring users have a clear context before diving into integration details.
  • [API Summary](https://doclab.privatelenderlaw.ai/introduction/api-summary.md): This is the first release of the API and user documentation. We expect enhancements to the API and documentation throughout the version 1 release. Glossary of Terms loan template : This is a JSON structure that shows all of the required parameters that are needed to create a successful document. loan document : This is the document that is created by the application when all the input values are combined with the loan template. The document can be genrated as a PDF. PLL User : This is a Private Lender Law employee involved in processing a loan. They will manualy review loan documents and may request additional information as required. status : this is the status that the loan has which is updated as the loan in processed through the loan doocument lifecycle. Statuses include initiated, temp, moreInfo, submitted, accepted, rejected, and completed . The term requests and loan document are used somewhat interchangeably in this version of the API. Changes may be made in future versions to provide more consistent syntax. Loan Document life-cycle The workflow below shows the typical loan document life-cycle. It includes the submission of required values, creation of loan documents, updates to the document based on status, issue generation, and comments that can be created and retrieved. It also shows where notifications are generated by the change in loan document status.
  • [API Setup and input form creation](https://doclab.privatelenderlaw.ai/introduction/api-setup.md): The API Setup and Input Form creation section guides users on setting up authentication parameters to securely access the Loan Document application. By obtaining a unique clientId and clientSecret provided by Private Lender Law, users can generate a token for authenticating API calls. This section is essential for establishing a secure connection initiating API interactions, and correctly creating and updating loan documents within the application. The base URL for the sandbox and the production environment is currently identical. The authentication parametrs fo rthe API determine whihc environment is accessed. Authentication Parameters Private Lender Law (PLL) will create a unique instance of the Loan Document application. Once this is created PLL will provide a unqiue clientId and clientSecret . This can then be used to create a token that is used in the authentication of each API call. White Listed IP addresses The API is current not restricted to a whitelist IP range. Loan Templates To test and utilize the PLL API, you must create forms capable of submitting parameters in the correct JSON structure. The PLL system provides loan templates tailored to specific loan types (categories) and locations (states). These templates are formatted as Microsoft Word documents containing merge fields, which are then populated with input form data to generate completed loan documents. The finalized documents can be exported as PDF files. The loan templates in the sandbox and the loan templates in the production enviroment are NOT shared at this time. Therefore, if a loan template is updated for production, then the sandbox version must be updated by a PLL user to be tested in the sandbox environment Input Forms Inpit forms can be created that confirm to producing the correct JSON Object to be processed by the API. The example requests and responses show typical code blocks for the most common environments. Example JSON Object for a Loan Template Below is an example of the JSON object structure used in the API to define loan template parameters: JSON { "lenderName": "HSBC", "category": "Personal Loan", "state": "New York", "variables": { "inputVariables": [ { "variableKey": "loanPurpose", "variableValue": "string" } ], "borrowerDetails": { "borrowers": [ { "variables": [ { "variableKey": "borrowerName", "variableValue": "string" }, { "variableKey": "income", "variableValue": "string" } ], "signatories": [], "notaries": [] } ], "notaries": [] }, "guarantorDetails": { "guarantors": [ { "variables": [ { "variableKey": "guarantorName", "variableValue": "" } ], "notaries": [] } ] }, "notaries": [ { "variables": [ { "variableKey": "notaryName", "variableValue": "" } ] } ] } }
  • [Getting a Loan Template](https://doclab.privatelenderlaw.ai/introduction/create-a-new-loan-document-copy-2.md): The request retrieves the loan template . This is the JSON Object that needs to be populated to create a loan document . The loan template that is retrieved is based on matching the lenderName , state and category properties. The variables property MUST be passed with a NULL value. The API endpoint is identical to the endpoint that creates and updates a loan document in this version of the API. However, when the variables parameter is provided with a NULL value, the API will retrieve the JSON object associated with the loan template , as opposed to attempting to create a loan document . The loan template will always contain the following: lenderName : This is the lender name category : This is the type of loan document state : This is the state or province in North America The combination of these three parameters is used to identify the correct loan template . In addition to the above parameters the loan template contains a variables block that has the follwing objects defined as arrays: inputVariables : This conatins specic details about the loan being requested borrowerDetails : This contains name and address information about the borrower and the notaries associated with the borrower guarantorDetails : This contains name and address information about the guarantor and the notaries associated with the guarantor notaries : This contains name and address information about the notraies involved in processing the loan Note: variable keys can be defined with spaces.
• [API Details](https://doclab.privatelenderlaw.ai/api-details.md): This provides a detailed description of the information needed to authenticate the AP{I, and process documents using the API endpoints. The functionality includes: Creating a new Loan Document Updating a loan document Getting a loan document by ID Getting loan document issues by ID Getting a list of all loan documents Getting comments by loan document Puting a comment on a loan document Subscribing to notifications
  • [Authentication](https://doclab.privatelenderlaw.ai/api-details/authentication.md): The `Authorization` header is used to authenticate and identify the client making the API request. It is a unique secret key assigned to each client, ensuring secure communication between the client and the server. This header must be included in all API requests that require client-specific operations or data access. If the `Authorization` is missing or invalid, the server will respond with an authentication error. Note: This currently uses the microsoft API call to retrieve the access_token . The API endpoint uses https://login.microsoftonline.com . The base URL must be replaced by this url. At this time authentication can only be done using this external endpoint. Future releases may include the ability to execute the API through the base URL. The access_token is current valid for 1 hour. Upon executing the API, the response should be checked for a 401 response, and then a new access_token created and resubmission of the API request.
  • [Document](https://doclab.privatelenderlaw.ai/api-details/document.md): The "Document" section describes API requests for managing loan documents, including creating, updating, and retrieving document information. Users can also address any issues related to loan documents during processing and access a list of all initiated loan documents. This section streamlines document management tasks within the API workflow.
    • [Create a new loan document](https://doclab.privatelenderlaw.ai/api-details/document/get-a-new-loan-template.md): The request creates a new loan document. The loan template that defines all the required key/value pairs is based on matching the lenderName,state and category properties. All of the parameters listed in the loan template with a non-null values must be provided for a successful submission of the loan document . The loan document may be created with a different status (listed below) based on the following scenarios. A Matching Template is NOT found If a valid template is not found based on the Lender (lenderName), State (state) and category (category) then: The loan document is created with a status of initiated . The responseCode will be 201 A unique requestId will be generated A PLL user will review the document and assign a template. After the PLL has assigned a template the loan document is then tagged as temp for further processing. With a Matching Template, but NOT all values provided If a valid template is found but some of the required form values are not provided or as null then: The document is then tagged as moreInfo for further processing. An issue will be created associated withe the loan document The responseCode will be 404 A unique requestId will be generated With a Matching Template and ALL values provided A matching template allows the endpoint to create a loan document with a temp status if: A unique requestId will be generated The responseCode will be 200 The document is then tagged as submitted ( responseCode:40 ) for further processing. A full list of response codes is provided.
    • [Update a loan document](https://doclab.privatelenderlaw.ai/api-details/document/create-a-new-loan-document-copy-1.md): The request creates updates an exisitng loan document . This typically is required when the loan document has a status of moreInfo after initial creation of the loan document. This endpoint is identical to the endpoint used to create a new loan document. To create this request the requestId of the loan document must be provided or the system will attempt to create a new loan document. This API call will follow the same rules with regard to a the status of the loan document . If all of the required values for the template have been provided then the status of the loan document will be marked as submitted . Howevewr, if some of the values are missing or have a null value, then the status will be marked as moreInfo and further submission of data will be required. This API will not be successful if the loan document has a submitted , accepted , rejected or completed status.
    • [Get loan document by ID](https://doclab.privatelenderlaw.ai/api-details/document/get-loan-template-by-requestid.md): This will retrieve the information about the loan document with regard to the status of all of the required information.
    • [Get loan document issues by ID](https://doclab.privatelenderlaw.ai/api-details/document/get-request-issues.md): This provides a list of all of the system generated key/value pairs that are preventing the submission of a loan document . These were either key/value pairs that were omitted when creating or updating a loan document or where values have been submitted as a null value.
    • [Get list of loan documents](https://doclab.privatelenderlaw.ai/api-details/document/get-loan-template-list.md): This lists all loan documents with pagination and optional filtering by status.
  • [Comment](https://doclab.privatelenderlaw.ai/api-details/comment.md): This section describes the API requests needed to retrieve and post comments on a loan document.
    • [Get comments by loan document ID](https://doclab.privatelenderlaw.ai/api-details/comment/get-comment-by-request-id.md)
    • [Put comment on loan document](https://doclab.privatelenderlaw.ai/api-details/comment/post-comment-on-request.md): This allows teh ability to post a comment on the loan document for review by a PLL USer.
  • [Notifications](https://doclab.privatelenderlaw.ai/api-details/notifications.md): This section describes the API requests that allow the loan document notifications to be subcribed to.
    • [Create a permanent connection to get loan request status notification.](https://doclab.privatelenderlaw.ai/api-details/notifications/create-a-connection-to-get-loan-request-status-notification.md): The `/notifications/events` endpoint is used to create a connection to get loan request status notification section enables clients to establish a real-time notification system for monitoring updates on their loan application status. By establishing a persistent connection with the server using Server-Sent Events (SSE), users can receive immediate updates as the status of their loan applications changes. This functionality provides clients with timely information on the progress of their loan requests. The connection remains open, allowing the server to push updates to the client as they occur. Each message is prefixed with `data: ` and followed by two newlines (`\n\n`) to comply with the SSE protocol. Clients’ system should manage automatic reconnections in case of network interruptions to ensure continuous updates. THE SSE response does NOT conform to a valid JSON response. The response should be treated as application/text
• [Response and Status Codes](https://doclab.privatelenderlaw.ai/response-and-status-codes.md): This list all the API response codes and document status codes. The document status codess are used to show where a loan document is in the document life-cycle.
  • [Document Status Codes](https://doclab.privatelenderlaw.ai/response-and-status-codes/response-codes.md): This is a list of status codes associated with a loan document . Status responseCode Description Temp 10 This is the initial status after a loan document has been received. Initiated 20 This is the initial status after a loan document has been called, but no information was passed into the variables. MoreInfo 30 This is the status of a document when is has been reviewed by a PLL user but additional values or missing values need to be provided Submitted 40 This is the status of a loan document when all required information has been provided Error 50 This is the status of a loan document if the JSON object of the loan document doe snot match the loan template Approved 60 This is the status of the loan document when the loan has been approved by PLL Rejected 70 This is the status of the loan document when the loan has been rejected by PLL Completed 80 This is the status of the loan document after PLL has completed the loan process
  • [API Response Codes](https://doclab.privatelenderlaw.ai/response-and-status-codes/api-response-codes.md): Code Status 401 UnAuthorize 200 Success 201 Created 404 Not Found 500 Error 601 Not Allowed 602 Invalid 701 Comment Added