Guides

Trx Monitoring: iframe integration

This guide describes integration of automatic documents request for transaction monitoring.

1. Case Creation

  1. Obtain credentials from Intrepid Fox
  2. Send HTTP POST to https://[partner_domain].intrepidfox.app/api/v1/cases with a JSON payload like this:
{
  "communication_id": "TRX-2024-001234",
  "invitation_email_recipients": ["[email protected]"],
  "case": {
    "case_kind": "monitoring",
    "company_id": "C-10042",
    "company_full_name": "Acme Trading Ltd",
    "company_reg_date": "2015-03-12",
    "company_industry_classification": [
      { "classification": "UKSIC2007", "code": "01120" },
      { "classification": "UKSIC2007", "code": "01160" }
    ],
    "account_opening_date": "2021-07-01",
    "trx_direction": "incoming",
    "trx_counterparty_full_name": "Global Suppliers GmbH",
    "trx_amount": 25350.00,
    "trx_currency": "EUR",
    "trx_date": "2024-05-28",
    "trx_description": "Payment for invoice INV-2024-118",
    "trx_ref_number": "REF-88172",
    "ultimate_debtor": "Acme Trading Ltd",
    "ultimate_creditor": "Global Suppliers GmbH",
    "modules": [
      { "module": "invoice" },
      { "module": "contract" },
      { "module": "transaction_rationale" }
    ]
  }
}
👍

This endpoint uses HTTP Basic Authentication, so the request shall include the Authorization header.

👍

For the full list of fields and their formats, see the API reference: Create Case

A few notes on the fields:

  • communication_id is optional — any string ID generated at your end which you can use to reference this case later. For example, you can pass your internal transaction reference number here; it will be echoed back in webhook calls and API responses.
  • invitation_email_recipients is optional — if present, an invitation to the dialog will be emailed to these addresses.
  • trx_direction is required and must be either "incoming" or "outgoing".
  • company_full_name and trx_counterparty_full_name are full legal names including the legal type (LLC etc.); the counterparty may also be a person.
  • trx_amount is a decimal number (like 253.50) and trx_currency is a 3-letter ISO 4217 code (like "EUR").
  • All dates use the YYYY-MM-DD format.
  • Besides UK SIC codes (UKSIC2007), industry classification also supports NACE, MCC and NAICS.

Modules

When creating a case via the API, you specify which "modules" will be turned on for the dialog with the user.

There are dedicated modules which ask for specific documents or specific information from the user. When these modules are used, the system validates documents and user answers against predefined rules. For example, the system will validate that company names in the invoice and contract match, or that the transaction rationale provided by the user makes sense and is consistent with the documents, etc.

For transaction monitoring cases, the dedicated modules are:

  • invoice — an invoice related to the transaction (issued to a client or received from a supplier)
  • contract — a contract underlying the transaction
  • transaction_rationale — asks the user to explain the rationale of the transaction
  • charter_agreement — a charter agreement
  • cargo_bill — a cargo bill
  • company_proof_of_address — a proof of address of the company
  • bank_statement_business_activity — a bank statement demonstrating business activity
  • license — a business license
  • insurance — an insurance policy
  • website — asks the user for the company website

When this is not enough, you can request additional documents or additional information from the user.

To request additional documents, use the other_document module, for which you specify the document name and intro text (instructions/questions) for the user:

{
  "case": {
    "modules": [
      {
        "module": "other_document",
        "document_name": "Transportation Documents",
        "question": "Please provide any document that contains information about the transportation of the items. Examples: a document outlining carrier information, shipping routes, or any required transit licenses."
      }
    ]
  }
}

The system will not perform any validation of the files uploaded via this module.

To ask arbitrary questions to the user, use the follow_up module, for which you specify a short subject of the question (used as the form title) and the question itself:

{
  "case": {
    "modules": [
      {
        "module": "follow_up",
        "subject": "Business Volumes",
        "question": "Could you please provide currencies, monthly number of payments and FX volumes of your business?"
      }
    ]
  }
}

The system will perform basic validation of the user answers (it will check that the answer is on-topic), but will not check the answer against any documents.

You can include as many other_document / follow_up modules as needed to collect all required information.

  1. Get the case ID and conversation ID in the response:
{
  "result": "case_created",
  "case_id": "9a7d81e0-f04a-4a40-9719-3598fb6bba10",
  "conversation_id": "9a7d81e0-f04a-4a40-9719-3598fb6bba10"
}

If the case cannot be created, the response will contain "result": "case_not_created" and a message field explaining the reason.

2. iFrame Launch

  1. Create a conversation link, inserting the conversation_id from the previous step:
https://[partner_link_1].intrepidfox.app/partner/[partner_link_2]?id=[conversation_id]
  1. Add HTML to your webpage:
<div id="intrepid-fox-container" />
  1. Use the script below to load the iframe with the conversation, inserting the link from step 1 into the LINK parameter:
const iframe = document.createElement("iframe");
iframe.setAttribute("src", LINK);
iframe.setAttribute("frameborder", "0");
iframe.setAttribute("width", "100%");
iframe.setAttribute("height", "100%");
iframe.setAttribute("style", "min-height: 100vh");

const el = document.getElementById("intrepid-fox-container");
el?.appendChild(iframe);

When the user completes the conversation, your back end is notified via webhook (see the next section), and you can close the iframe.

3. Obtaining the Results

When the conversation finishes, Intrepid Fox calls your webhook to notify you about the event, and you can fetch the case results via the Case Result API.

Webhook Notification

When the conversation finishes, Intrepid Fox calls a webhook (sends an HTTP request to an endpoint hosted at your end) to notify you that the conversation is complete. The JSON payload of the notification:

{
  "event": "chat_finished",
  "case_id": "9a7d81e0-f04a-4a40-9719-3598fb6bba10",
  "conversation_id": "9a7d81e0-f04a-4a40-9719-3598fb6bba10",
  "communication_id": "TRX-2024-001234",
  "pdf_report_link": "https://...",
  "web_report_link": "https://...",
  "client_documents": [
    {
      "document_id": "5c2f81e0-f04a-4a40-9719-3598fb6bba10",
      "document_type": "invoice",
      "document_name": "Invoice",
      "rejected": false,
      "download_link": "https://...",
      "original_files": [
        { "filename": "invoice.pdf" }
      ]
    }
  ],
  "legal_entities": [ ... ],
  "main_entity_id": "...",
  "conversation_log": [ ... ]
}
👍

HTTP Basic Authentication is used in the webhook calls (so the request will include the Authorization header).

👍

For the full payload specification, see the API reference: chat_finished webhook

A few notes on the payload:

  • case_id and conversation_id are the same IDs which were returned by the POST /api/v1/cases request.
  • communication_id is the same ID which was passed when creating the case (for example, your internal transaction reference number).
  • pdf_report_link is a URL to download the PDF report, protected by your service credentials. web_report_link is a URL to the web version of the report, protected by your user credentials.
  • client_documents lists the documents uploaded by the user, with download links and a rejected boolean flag for each.

Case Result API

To get the case results, fetch them via the API:

GET https://[partner_domain].intrepidfox.app/api/v1/cases/[case_id]/result

While the results are not ready yet, the endpoint responds with:

{
  "case_id": "9a7d81e0-f04a-4a40-9719-3598fb6bba10",
  "status": "not_ready"
}

Once the conversation finishes and the report is generated, the endpoint responds with "status": "ready" and the result object containing the report links, the uploaded documents with extracted data, and all legal entities known within the case.

👍

For a detailed walkthrough of the result structure, see Obtaining Case Result, and for the full response specification, see the API reference: Get Case Result