> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiant.finance/llms.txt
> Use this file to discover all available pages before exploring further.
# Joining the Valiant Platform
> Technical guide for finance partners integrating with the Valiant platform
# Introduction
This document provides an initial outline of the technical preferences, processes and ideal workflow for finance partners to seamlessly join and be integrated into the Valiant platform.
Valiant offers a comprehensive integration framework to onboard finance partners that is designed to suit available tech capability while also supercharging any existing and required internal processes. This includes support for:
1. **Multi-layered validations** – Applications undergo three phases of validation (frontend, backend, and finance partner-specific) to ensure data quality and compliance before submission
2. **Multiple submission methods** – Applications can be submitted via API (preferred) or email, with API submissions providing the most efficient and feature-rich experience and email helping fill the gaps where data may not be able to be accepted in a structure way via API
3. **Built-in document generation** – Any required supporting documents (booking spreadsheets, etc.) can be generated dynamically at submission and formatted to finance partner specifications to help power and accelerate internal process
4. **Support for real-time status updates** – Accurate application statuses can be maintained through push notifications (webhooks, preferred) or pull mechanisms (polling), with manual CSV imports available as a fallback
5. **Support for auto-decisioning** – Valiant's platform provides reactive and dynamic notifications and UI flows where auto-decisioning is available
**Important:** See below for a detailed sequence diagram that outlines a step-by-step overview of API submissions.
# Validations
When a customer submits an application via the Valiant platform, before an application is submitted to a finance partner three phases of validation checks are run:
* **Frontend validations** – basic input format and data quality validations run client-side where speed of communicating a validation fail to a customer is critical
* **Backend validations** – deeper and more robust security, model and database level validations
* **Finance partner API requirement validations** – input and mapping validations required for valid finance partner submission as outlined in finance partner API docs or discovered in testing – folded into our backend validations so we can move any validation issues further up the funnel
# Application submissions
Valiant can submit applications to finance partners automatically via two mediums:
* **API** – The preferred submission method, where Valiant maps our application format and submits applications directly to a finance partner
* **Email** – A backup submission method where an email with summary of application is sent to a nominated inbox
## API submissions
API submissions are Valiant's preferred method. Both `JSON` and `XML SOAP` APIs are supported.
API documentation is a must-have for an effective implementation. Documents in Swagger, OpenAPI or other formats are all accepted – please share with [integrations@valiant.finance](mailto:integrations@valiant.finance).
### Ideal API capability
While submitting applications is the primary goal of any finance partner integration when joining the Valiant platform, the submission itself is ideally the first part of a broader suite of API capability offered by a finance partner to help manage interface with and manage application and the application pipeline.
Example endpoints and the ideal API capability we would hope to be able to interface with includes:
> e.g., `POST` to `/application`
* Primary app submission entry point
* Critical in any API implementation
* Must return a unique finance partner application ID for Valiant to reference across reporting and other processes
> e.g., `GET` to `/application/:id`
* Fetch a single application, primarily for manual status checks / data reconciliation
* Critical in any API implementation
* Includes latest status of the application and ideally includes a timestamped status history if available
> e.g., `GET` to `/applications`
* Fetch a list of applications, either a complete paginated list or filterable via query parameters (or alternatively a `POST` body if `POST` endpoint)
* Accepts query params to filter a list of applications by status or datetimes support for filter by – e.g., `updated_after` to filter for applications updated since the provided timestamp – `/applications?updated_after=2025-01-01T12:00:00Z`
> e.g., `POST` to `/application/:id/documents`
* Attach supporting documents and files to an existing application
> e.g., `PATCH` to `/application/:id`
* Push application updates directly to finance partner
* Accepts both minor 'edits' and major updates that would be considered an 'appeal' from a credit perspective with corresponding
* Can including support for withdrawing or expiring applications – i.e., setting of specific statuses from the Valiant side
**Note:** There is a strong preference for `JSON` APIs if available – please note integration and testing timelines for `XML SOAP` APIs will likely be longer vs. a `JSON` API implementation.
## Email submissions
Email submissions are available to supplement API submissions.
* Can be sent to a nominated finance partner inbox for processing / reference by a specific team or for automated parsing
* Allow Valiant to share additional application metadata collected during the quoting and application process, like risk factor assessments and other metadata, that might not be accepted in a structured way via API
* Often leveraged for audit and compliance record-keeping purposes
* Where supporting documents were uploaded or generated and are required as part of a submission, tokenised links to download the documents as attachments are included in the submission email
# Supporting documents
When processing an application, Valiant can also generate and submit many supporting documents that might help facilitate or accelerate an internal process requirement. These include:
* Spreadsheets – e.g., doc request, bill of materials or booking spreadsheets required for internal processes
* Documents – e.g., Word documents or PDFs application forms or other specifically formatted word processor documents
* Images – e.g., ID document captures or other images captured as part of the Valiant application journey
These documents can be generated and uploaded / attached to any supported submission method (API, email, etc.).
**Note:** While we have generic templates for many document types, we are also able to implement the generation of docs that follow finance partner specific templates that might be required internally – if so, please provide Valiant a copy of the required template for implementation.
# Status updates
Maintaining an accurate representation of the current status of a given Opportunity in the Valiant system is critical to providing a beautiful customer and team member experience. Changes in status trigger a number of UI features and real-time notifications on the Valiant platform.
## When automated updates are available
Where an automated solution via technology is available, we can support and process status updates via both:
**Push** – Updates are pushed from the finance partner via `webhooks` or another event-driven pub/sub-style push notification protocol
* Needs to be made available by the finance partner and provides real-time updates, reducing latency and ensuring immediate status accuracy when changes occur
* Any push notification received via a `webhook` should ideally include:
* The finance partner's unique ID for the application / target object
* The event that was triggered – e.g., a status change or other event – and its value
* The full timestamp of the event – e.g., `YYYY-MM-DDTHH:MM:SSZ` – so we have the timestamp of the event from the source of truth system
* All webhooks received are added to a processing queue so if there is a processing delay or we are processing a retried event, the event and processing time may be misaligned
* All requests made to subscription endpoint are processed via an API gateway layer (Cloudflare worker and Cloudflare queue) that receives the payload and then will pipe through to our platform. In case of platform unavailability, this service will keep retrying with exponential backoff until success
* In case of failure at our subscription endpoint worker (which should only really happen during planned maintenance) or we are receiving a retried – ideally the partner system should also continue attempts to push the update with an exponential backoff over a few hours before marking as failed
* Ideally we do not need to run a manual poll to fetch additional required data to process a status update after receipt of a push notification, however this can be implemented if required
**Pull** – Valiant manually polls applications directly via periodically run background jobs to check for status updates
* Ideally serves as a backup to a push protocol and ensures that any missed push notifications don't result in permanently out-of-sync data
* Where relied on as the primary status update process, we poll with an exponential backoff with cadence determined as a function of current application status and number of previous polls completed
* Can result in a significant number of requests to finance partner API if there are a large number of open applications!
* While polling individual apps is supported, to minimise unnecessary polling requests, ideally we are able to poll a queryable applications `index` – e.g, `GET` to `/applications` – where we can filter applications for specific attributes, including collecting all applications updated after a specified timestamp
**Important:**
To maintain an accurate status history and avoid unnecessary manual polling requests when there are large application volumes, there is a **very strong preference for inclusion of a push mechanism** in any finance partner implementation, ideally via `webhooks`.
If a push solution is not available, there is significant risk that status updates are missed as multiple status updates may occur between polls – especially during statuses with usually short turnaround windows like `Docs Out` → `Docs Signed`.
We will always implement both **push** and **pull** protocols if they are available, leaning on **pull** as a backup / failsafe check.
## When no automated solution is available
In the case where a push or pull solution via technology is not supported, we are able to backfill Opportunity statuses and events with relevant timestamps via a daily/weekly or monthly `CSV` import where the `CSV` includes a relevant unique identifier that is tracked in Valiant's system – e.g., Valiant app ID, vendor partner quote ID, etc., and timestamps for the events we are looking to track.
**Note:** A manual `CSV` upload solution is not ideal and only offered in the case where a push/pull solution via technology is not available.
# API submission sequence / interaction flow with both push / pull updates
```mermaid theme={null}
%%{init: {"zoomEnabled": true, "pan": true}}%%
sequenceDiagram
autonumber
%% Participants. %%
participant FrontlineTeamMember as Frontline Team
participant Customer as Customer
participant ValiantFrontend as Valiant Customer Frontend
participant ValiantServer as Valiant Server
participant FinancePartnerServer as Finance Partner Server
participant ValiantPortal as Valiant Partner Portal
participant FinancePartnerTeam as Finance Partner Team
rect rgba(255, 200, 0, 0.1)
alt Global webhook subscription available
Note over ValiantServer,FinancePartnerServer: If 'global' push / webhook subscription is available – i.e., can
subscribe to receive updates for all applications and do not need
to subscribe on an app-by-app basis – subscription on
Valiant side should already be established.
FinancePartnerServer -->> ValiantServer: Begin listening for application updates
end
end
%% App invite. %%
activate FrontlineTeamMember
FrontlineTeamMember ->> Customer: Invite customer to view quote
and complete credit application
deactivate FrontlineTeamMember
%% App completion. %%
activate Customer
Customer ->> ValiantFrontend: Complete, sign and submit
Valiant application form
(including privacy and consents)
deactivate Customer
%% Frontend validations. %%
activate ValiantFrontend
critical Frontend validations run
Note over Customer,ValiantServer: Client-side basic input format and data quality validations.
option Invalid application
rect rgba(255, 0, 50, 0.1)
ValiantFrontend -->> Customer: Display validation error
end
option Valid application
rect rgba(0, 255, 77, 0.1)
ValiantFrontend ->> ValiantServer: Submit application
deactivate ValiantFrontend
activate ValiantServer
Note over ValiantFrontend,ValiantServer: Including timestamps and consent
audit data (IP address, device, etc.)
end
end
%% Backend validations. %%
critical Backend validations run
Note over Customer,ValiantServer: Robust model, database and selected finance partner API requirement validations.
option Invalid application
rect rgba(255, 0, 50, 0.1)
ValiantServer -->> ValiantFrontend: Return validation error
ValiantFrontend -->> Customer: Display validation error
end
option Valid application
rect rgba(0, 255, 77, 0.1)
ValiantServer -->> ValiantFrontend: Return success
ValiantServer ->> ValiantServer: Commit application
end
end
%% Submit app to finance partner. %%
ValiantServer -->> ValiantPortal: Opportunity updated in Portal
ValiantServer ->> ValiantServer: Credit application mapped / data transformed
to required finance partner format
ValiantServer ->> ValiantServer: Supporting docs (booking spreadsheet, any
supporting PDF, etc.) generated where required
ValiantServer ->> FinancePartnerServer: Submit credit application to finance partner (POST)
deactivate ValiantServer
activate FinancePartnerServer
FinancePartnerServer ->> ValiantServer: Confirm successful submission (20X response)
Note over FinancePartnerServer,ValiantServer: Valiant captures unique finance partner application ID
returned in response to use as reference in future flows.
ValiantServer -->> ValiantPortal: Opportunity status updated to 'Applied'
```
You can view the [full interactive sequence diagram](https://mermaid.live/view#pako:eNrNWetu28gVfpUBgYVtgFJ8iWxHCAIk9jow0G3cONktCv9YihxJU5MzzHBoWQ1S9B36An2WPkqfpN-ZGYoUL5aDbosaQWyRM3Nu3znnO6OvQawSHkyD0Wh0J2Ml52IxvZOMzZU0V1Em0vWUFevC8GxUipAVkSxGBddiHtKqlY7yKZtHacHpY8G_lFzGfMq-fruT9sjq0aWIFjrKaFVUGiXLbMb1naTPP_zAbiJtRCzySJpijAf0OK-fsSsNdVIh-SceZT9x2suion7M6Hl700VZGJW5ldXf7TU_R6nAb3sQlwkt9Y_q7dXLgb23XD84IdVO96Rjg5ARHEGmSq7rXf458y8Gdvuzb5Q2UdoUVm1zb54WSl7qE-m8R3s1jw3Ti1m0fzyZhOz48DBk9G98dIAFBsFLDXufqhmUWPHZUql7VpSzItYiN0JJFj1EIo1mKafltOH3ynCmyNYtf4V97piy6znbW9jj91heFkv2ol-MKGpJ7F9_-zsTYz4OWRzJ1zP94o1fO-PMKLKJiwfOyjyJDC8Abfg9hRPzPBVxROfhNAQ_UUwqwyTniT0Fe-uDyDZJe0az9Qi_2CwqoAXJ3tJMOQ2q8BQi4axYqjIFuFLNo2TNcBovDFQXxZIn48pTvQAZjd682fbclL3jCyEZdgOVQi6cQbUxlaHuXEI1o9BaBPt8ewv9hXwQhlfZFsVGPGBXX6rR-74MJNWqLEHo7HksrtIG3nsQfMW-lECA9Qn5OFZZnnJap3kiTFNvEpPwpxVp6O9PwsaODc1s36Rxw5FVRk_ZhVcHlU0spEUBopkJsxXEpnPh7My-3BcyTsuEApBryI3XzBmImocydtAyp9bJ27CpOQ-QkjgYdixp1ycbSWANCY4M7DuC6VK6VK0zr5IdtoB0kQqoOrIYJTjHAEVeGmtjZFxORCZCCLHPrLc0JUWUgzwiTy_asexUExSSyaaYMPvTtm-0jalLUeRp1BTMuNZKu-2-Jnstft6lA0RbNc7OdujQzbhbi4nu4VsRbp1TrWi_r-s7_XTKY7W9HavrDdqMyKh8ZHnRBJzLsJJyysZs__qGRUmieVGE0PJBxAA5N_H4YMt5zarwLorvBwC5gVzPGoc4QNPsRtxHNcMbloF0pKFVFLjjLu94ilDxhM19d8p9d3p7c40ofimF5hkM_e-hsKfk1pXiIzellgNI_L8C8nPMKMo4BjIGdnYTAHWyNwHaKCIY1clCPaAVzQpQw7o6IjNlH_Icf5WSCo_raAnKU4Pn7Fa602JYhg8454XLEaNBZ6nY1Q3fA62LQlcTnyX3trSqU64mKi7Y_gz8hT4VOREANH1uQmB-7bnKZvXN5ZXPUbbgEGptXi255hu9-hXoJ1M-EN1O2xMXtn_z4fZTu2l1SlbdnXskWp7QS2L6AIVRQ2cVEOdl6hpvUZB--8eHf4TJRU61zSpVl5Y-Ce0yUzXuOMoBd3A-wAhzSMfopk-uL204tE0Qh7VKA_JXSWUKtY7PEQ46A-_nJZ3O5qlauVL0fahGETdlsQE3hPz6lhTiya8Dhw3FuYm3kooknZqqKHHHDsd6t8JtMGc4tMG9cXqiVpJkEUXOh7Kzqz3ROo9RF3Se4VBGvYxOlSrDcpf0M_XI9sWcCiRPRnD8bN22aciaHhY5JTCJOYoxyhaos1mC62xo6xJBrkgqnLfkQrvW2oAKtStaN-NcNhCcrj15NL1uH9CwbhJerZpBk_AtjK4sAu04k_ji0RDuuqhh_DFHr_DNmYYDyR8xiRieF22OPZDFQwXAE4VbCCnzbfyCBCujYpV2KMNmNdWzxdpq5IwgUPUMLmyuVdbnPd8gb2gwrMS15kA_LRaujrom9X0j6C-23laqYKKkeY1mUWoKPYp5Ic_O1o-Y3hAL3RxsLbqlYm70pScHvaf-B7Ngw3uYfQe8l0USVB9ZnKa_lQNpmqZksE5MU3xA8vpjxs808g8lR_FumkUaYmSJ7xdalYD9n9WszWZvtKLU2EbphtCmSuXsd_RfKY3Yugygy4W9OFUFT_bak9Tz7adbrlHCY0G1jSLTvLIIEXyfphtHrYRZIpR_fTlxmc1B7JOCKVQBvRJFY7L-THwYolDl4djIcQUMbyhk8p6tVckK9HwuvXvhi_e8klPZ725yBjKpooW9zfz16747iY_-kqWLPQZVpfF0MYUdAwDs56ID0kr5HDhs-OnzOdMVUL98kifsv__xk8_OYaa08XyFwo73d5XgRgGtzmhqUVETt9Sn9mcZAwIL5JgHPeW0VISrBUEldwc9Gd7e2HoaRBBFvmwLed6c-5yoghOCZyDTt8tZlSAvbF74YqD5YMyfZrAbZ110XeUB-1t5qt9Pz2i_3-vOHk0qzHSnqN3TYkX9Pjt39FDWrTlsqPvtZl5qviG_VcZ5jAuDCHlh1peYlurZbJvPDMgf5lXQHiWUWq6vuS8nzJfbA0uiHBPF-wjRgmbIQyptRQGPZtVdiyoNeCLf8DFC0D__4e6hYYVW9AxGogeQF_x7awy2YJ6GD1q2VNagblxQ_6lgWJcNV7a3IyKQB3sq53KvWjPYsWj-4JVjOcWRLpX41BrkZ4-QXcu5ApSds0O6bLXGhHbVJQ0BH0oMsPavW7GQtAgkz6TufuYdSA1Pal3-p6lvO0zTP1KtGt18p3-s35MBD_34mDuXXPqYhuwXxDPR0UqG7KqkgA7Z3We0jXFTWcvgDUhJrxsGj94xZzrrm0lLXwwQsXm6UDbaZ33PE4TBQoskmBpd8jBAPiFZ8DH4au8AA9CVjN8FU_yZRPr-LriT37Anj-SflMqqbYjbYhlM7TeHYeDs818RbpZQfugLBNgE01f2hGD6NXgMpkdnJ-PTo8nh6enx-dnx5OgkDNbB9OToZHx2en56dHx2eH50dHj-LQz-YkUejs-w7nzy6vxkcnr88vTVJAzoSkTpn9yXn_Y70G__Bm_MRd0) for more details.