Quickstart Guide ================ Overview -------- This guide is intended to give Vidual partners and customers a high level overview of using and interacting with the Vidual applicant and loan verification API. As a quickstart, the guide will cover the essentials you need to start integrating with the platform. For more in depth technical and implementation details, please consult the documentation or contact your Vidual account manager. It is expected that the audience of this guide is familiar with the basic concepts of the Vidual platform and integration with APIs. What you need ------------- To get started with the Vidual API, you will need the following: * A Client ID - Provided during implementation * One or more decision rule codes * Bank name reference information - :doc:`bankref` * A consumer to interact with the webservice. This can be any tool or language which supports making HTTP requests. cURL or Postman can be used for experimentation. A OpenAPI/Swagger definition for the webservice is available at ``_ The basic methods ----------------- The simplest workflow available is to upload applicant details and statements and to retrieve the results from a decision rule. To implement this workflow, you need to call two methods: * Applicant/GetPDFFiles.aspx - Upload applicant details, run the OCR process and execute the decision rule * Applicant/getUploadResults.aspx - Retrieve the results from the above process. Full endpoint documentation is available at ``_ A note on request headers ------------------------- The Vidual API uses the Authorisation header in a number of different ways, depending on the specific call. For the purpose of this guide, the Authorisation header is used to provide your decision rule code. The Authorisation header is always provided as a Basic auth header, with your decision rule code encoded as a Base-64 string. For example, for a decision rule code of "TEST1", the header should be represented as follows: .. code-block:: html Basic VEVTVDE= And in the request header .. code-block:: bash POST /Applicant/GetPDFFiles.aspx HTTP/1.1 Authorization: Basic VEVTVDE= A note on PDF uploads ---------------------- The API is designed to take only Base-64 encoded PDF files. Attempting to upload binary streams or any other method will result in an error. Depending on your consumer language, you might have to implement a procedure to Base-64 encode the contents of the PDF Statements before calling any of the methods that accept PDF files. Step 1 - Store Applicant Details and Run a Decide ------------------------------------------------- The most basic workflow commences with the upload of the applicant details and PDF statements. For the purposes of the quickguide, we will use a fictional applicant - John Smith, who has the following: * A single statement for ABSA * Gross income of $10,000 * Net income of $8,000 * Expenses of $2,000 We will be running the TEST1 rule against the applicant The /Applicant/GetPDFFiles.aspx method is used to initiate the process. Given John's information, the request will take the following shape: .. code-block:: bash POST /Applicant/GetPDFFiles.aspx HTTP/1.1 Authorization: Basic VEVTVDE= Content-Type: application/json { "appDetails": { "firstName": "John", "surname": "Smith", "idNumber": "ID1", "appRefNumber": "Ref1", "gross": "10000", "nett": "8000", "cmiVariance": "0", "lpVariance": "0", "expenses": "2000", "uniqueCode": "RULE1" }, "bankNames": [ "ABSA" ], "fileNames": [ "ABSA_JS.pdf" ], "pdfBytes": [ "dGhpcyBpc.......yBhIHRlc3Q=" ] } If the request is successful, the following result will be returned: .. code-block:: json { "uuid": "e7c67189-7f11-4481-a233-072690b23994", "statusMessage": "Your request is being processed - please check in a minute or two for your results" } Step 2 - Get Results -------------------- Once a call has been successfully made to the GetPDFFiles.aspx method, the results of the process are available by calling the Applicant/getUploadResults.aspx method. To call this method, all you require is the UUID from the call in the previous step. Please note that the process initiated in Step 1 may take some time to run, so it is recommended that you poll the Applicant/getUploadResults.aspx method until a result has been returned. The method only requires the UUID as a query string parameter. The request to the method should look like the following: .. code-block:: bash POST /Applicant/getUploadResults.aspx?uuid=e7c67189-7f11-4481-a233-072690b23994 HTTP/1.1 If the process is still running, you will recieve a response similar to the below: .. code-block:: json { "uuid": "e7c67189-7f11-4481-a233-072690b23994", "status": "These results are not ready yet - please try again in a short while", "results": "" "pdfDets": "" } Once the process is finished, the response will look like the below: .. code-block:: json { "uuid": "e7c67189-7f11-4481-a233-072690b23994", "status": "Success", "results": { "uuid": "string", "bankName": "string", "clientId": "string", "decisionRule": "string", "decisionType": "string", "incomeTolerance": "string", "payerMatchType": "string", "payor": "string", "purge": "string", "searchDays": "string", "startDate": "string", "transAmt": "string", "transInt": "string", "transType": "string", "bankInfoClean": "string", "bankAccount": "string", "decisionResult": "string", "decisionDesc": "string", "processEndDt": "string", "processStartDt": "string", "runStatus": "string", "runTimeMs": "string", "stepResult1": "string", "stepDesc1": "string", "stepResult2": "string", "stepDesc2": "string", "stepResult3": "string", "stepDesc3": "string", "stepResult4": "string", "stepDesc4": "string", "stepResult5": "string", "stepDesc5": "string", "stepResult6": "string", "stepDesc6": "string", "stepResult7": "string", "stepDesc7": "string", "stepResult8": "string", "stepDesc8": "string", "stepResult9": "string", "stepDesc9": "string", "stepResult10": "string", "stepDesc10": "string", "decisionUuid": "string", "clientDivId": "string", "applicantTag1": "string", "applicantTag2": "string", "application": "string", "version": "string" }, "pdfDets": "dGhpcyBpc.......yBhIHRlc3Q=" }