API services for finance providers

Requests are sent to an endpoint of your choice. HTTP auth can be enabled, as can mutual TLS authentication. Contact us to discuss additional authentication mechanisms such as OAuth etc.

Example requests

Here is an example of a private individual proposal: rosetta_example.xml

An example response is detailed here

Structure

The structure of a private individual proposal is shown below. Examples are given in fields that are typically completed on a normal proposal.

A base level of validation is applied, but specific validation can be implemented on request.

/rosetta

An attribute named "live" indicates whether the proposal has originated from a system configured to be live (1) or test (0).

/rosetta/application

/rosetta/routing

The proposal can be uniquely identified by the client and client_reference taken together.

/rosetta/application/applicant_section

Multiple applicant sections may be provided. The following attributes are also required:

/rosetta/application/applicant_section/details_section

/rosetta/application/applicant_section/residence_section

At least one of flat / house_name / house number is required by the base validation.

/rosetta/application/applicant_section/employment_section

/rosetta/application/applicant_section/affordability_section

This section relates to Black Horse only.

/rosetta/application/applicant_section/bank_section

/rosetta/application/vehicle_section

/rosetta/application/finance_section

/rosetta/application/finance_section/options_section/option

/rosetta/application/finance_section/accessories_section/accessory

/rosetta/application/finance_section/vaps/vap

VAPs will only appear in the Rosetta XML if they are set to be added to the proposal as opposed to being funded separately. If a lender does not intend to fund some or all VAPs, it is up to the lender to re-stack the proposal to cover the VAPs cost from the customer deposit, if sufficient.

/rosetta/application/extras_section/notes

/rosetta/application/extras_section/data

Extra data values are configured per-lender and can be free-text or fixed values from a drop-down.

A common use case for extra data is to capture additional information at the point of sending, such as affordability questions.

Send decision

Lender decisions can be either pushed or polled. For pushed decisions, the lender should make a request into the send decision endpoint at /html/services/rosetta/send_decision.php with the following request body as a minimum.

<?xml version="1.0"?>
<send_decision>
  <username>provided by dealtrak</username>
  <password>provided by dealtrak</password>
  <reference>lender's application reference</reference>
  <status_id>2</status_id><!-- from the list of destination status IDs -->
</send_decision>

A full example with all optional sections:

<?xml version="1.0"?>
<send_decision>
  <username>provided by dealtrak</username>
  <password>provided by dealtrak</password>
  <reference>lender's application reference</reference>
  <status_id>2</status_id><!-- from the list of destination status IDs -->
  <original_lender_status>Pending E-Sign</original_lender_status><!-- optional -->
  <note>A free text note</note><!-- optional -->
  <conditions><!-- optional -->
    <condition>Service history required</condition>
    <condition>Subject to successful affordability check</condition>
  </conditions>
  <finances><!-- optional -->
    <finance name="APR">16.9</finance><!-- name attribute is arbitrary -->
    <finance name="Monthly Repayment">267.01</finance>
    <finance name="Total Repayable">12816.48</finance>
    <finance name="Term">48</finance>
  </finances>
  <tasks><!-- optional -->
    <task status="complete" time="2022-05-04T12:34:56">
      <title>Provide proof of income</title>
      <description>Copies of customer latest bank statement and payslip required</description>
    </task>
    <task status="incomplete" time="2022-05-05T12:34:56">
      <title>Dealer invoice</title>
      <description>Upload the dealer invoice</description>
    </task>
  </tasks>
  <lender_questions><!-- optional -->
    <question id="asdf1234">
      <title>Contra Settlement</title>
      <type>multiple</type>
      <description>Which of these existing agreements does this application contra-settle?</description>
        <options>
          <option value="827373737">Agreement 827373737, AB12CDE</option>
          <option value="928374743">Agreement 928374743, CD24EFG</option>
        </options>
      </question>
    </lender_questions>
</send_decision>

Send document

To send PDF documents or URLs into DealTrak, use the following request to /html/services/rosetta/send_document.php:

<?xml version="1.0" encoding="UTF-8"?>
<send_document>
    <username>provided by dealtrak</username>
    <password>provided by dealtrak</password>
    <reference>lender's application reference</reference>
    <description>Document/link filename or description</description>
    <status>New</status><!-- free text status description, eg: New, Completed etc -->
    <!-- for URLs -->
    <document type="url">https://www.youtube.com/watch?v=dQw4w9WgXcQ</document>
    <!-- OR for PDFs -->
    <document type="pdf">base64 encoded data</document>
    <!-- send only one <document> at a time -->
</send_document>

Multiple requests may be made in order to provide multiple documents or links. Documents pushed with the same name as a previous document will replace older versions.