Trust Analyzer Implementation

New to the Trust Analyzer? Start with the Trust Analyzer overview for what it does and how the flow fits together, then come back here for the full walkthrough. This guide covers both the Portal walkthrough and the API walkthrough. Use whichever fits your team — they produce the same result. Currently supports Australian trust deeds only.

Portal Walkthrough

Prerequisites

An organization entity already created in the Portal.
Trust Analyzer enabled for your environment, with the workflow assigned and turned on in Ops Centre. Contact your FrankieOne representative if you don’t see it yet.
Available for Australian trust deeds only.

Open the Trust Analyser tab

From the organization’s Overview page, select the Trust Analyser tab.

Trust Analyser tab on the organization Overview page — Trust Analyser tab, no document uploaded yet

Upload the trust deed

Select Upload trust deed, then either drag and drop the file or select Browse File to choose the PDF (max 20MB).

Add Document dialog for uploading a trust deed — Add Document dialog with drag-and-drop and Browse File

Track progress

The deed appears in the Trust deeds table on the same tab, with its status shown in the Status column — through analysis, then To be reviewed once the extracted data is ready.Re-uploading and re-analysing an unchanged trust deed reuses the existing valid analysis rather than running a fresh one. If the attachment is later updated or deleted, prior analyses for that document are marked stale.

Trust deeds table showing a deed with status To be reviewed

Review and confirm

Select the deed to open the review screen: the deed itself on the left, extracted fields on the right. Each field carries a small reference marker (e.g. 1a, 1b, 2a) — these link back to the exact location in the deed the value was extracted from, so you can verify quickly without re-reading the whole document.Correct any field that needs it directly in the form. When you’re satisfied, select I have reviewed and accept the data in this trust deed and select Save — review and confirmation happen on this one screen, there’s no separate confirm step.If the trust type could not be detected, it’s shown as unclassified with the reasons why. Trust type is inferred automatically and isn’t something you can set or override from the Portal — the analysis can’t be confirmed until the deed is successfully classified.

View associated parties

Once saved, confirmed parties are marked as an Associated party directly on the same screen, and appear as part of the organization’s ownership and control structure.

API Walkthrough

The examples use the UAT base URL (https://api.uat.frankie.one); swap in your production base URL when you go live.

Prerequisites

Before running a trust analysis via API, make sure the following are in place:

The Trust Analyzer enabled. The GLB-Trust-Analysis workflow has to be enabled for your environment on the V2 platform. If you don’t see it yet, contact your FrankieOne representative to have it turned on.
An organization entity. Trust analysis runs against an existing organization, the focus entity that holds or is associated with the trust. Create it first and keep its entityId. See Managing Organizations for how to create one.
The trust deed uploaded. The deed must already be attached to that organization as a TRUST_DEED document. You upload it in Step 1 below and keep the returned documentId, which is what the workflow analyses.
A service profile. The serviceName of the Service Profile the organization is assessed against, for example DEFAULT. Your FrankieOne representative provides this when the workflow is set up.

Step 1: Upload the Trust Deed

The Trust Analyzer works on a deed that is already attached to the organization, so upload it first. Send the PDF as a base64-encoded attachment on a TRUST_DEED document, and keep the documentId from the response. You pass that documentId to the workflow in the next step.

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "document": {
        "type": "TRUST_DEED",
        "attachments": [
            { "data": "JVBERi0xLjQ...base64-encoded PDF..." }
        ]
    }
}'

Step 2: Execute the Trust Analysis Workflow

Execute GLB-Trust-Analysis against the organization’s entityId. Pass the documentId of the uploaded trust deed in executionVariables. This is the only execution variable the workflow needs; the trust type is detected from the document, so you don’t supply it. The optional comment is recorded on the workflow’s audit trail. The response returns a workflowExecutionId. Keep it: you use it in the next step to track the execution.

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/GLB-Trust-Analysis/execute' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "executionVariables": {
        "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7"
    },
    "comment": {
        "text": "Initiating trust deed analysis for onboarding"
    }
}'

{
    "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
    "requestId": "01K4VK7KWN6HEA43AQ0F13JZPT",
    "serviceName": "DEFAULT",
    "workflowExecutionId": "01K4VK7QDJG631AWFKWYVE85Z5"
}

Re-executing on an unchanged trust deed reuses the existing valid analysis. No new analysis is run and you are not charged again. If the deed’s attachment is later updated or deleted, prior analyses for that document are marked stale.

Step 3: Track the Workflow Execution

Trust analysis is asynchronous. The execute endpoint returns 202 Accepted with a workflowExecutionId. Retrieve the execution result and poll until workflowResult.workflowExecutionState is no longer IN_PROGRESS. When analysis completes, the workflow result moves to REVIEW, indicating the extracted data is ready for you to review and confirm. Poll every 5 to 10 seconds.

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/GLB-Trust-Analysis/executions/{{workflowExecutionId}}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

Step 4: Retrieve the Analysis Results

Fetch the analyses for the document. Use the showResults query parameter to control which analyses are returned: LATEST (default), COMPLETE, or CONFIRMED. Each analysis carries a status (PROCESSING, FAILED, COMPLETE, or CONFIRMED), the detected trust type, the extracted parties, and a references map that points each extracted value back to its location in the deed.

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents/{{documentId}}/analyses?showResults=LATEST' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

{
    "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
    "analyses": [
        {
            "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7",
            "analysisId": "01K4VK7QDJG631AWFKWYVE85Z5",
            "status": "COMPLETE",
            "documentInformation": {
                "type": "TRUST_DOCUMENT",
                "trust": {
                    "name": { "value": "The Doe Family Trust", "referenceIds": ["r1"] },
                    "type": { "detected": "DISCRETIONARY" },
                    "trustees": [
                        { "entityId": "org-1", "entityType": "ORGANIZATION", "referenceIds": ["r2"] }
                    ],
                    "settlors": [
                        { "entityId": "ind-1", "entityType": "INDIVIDUAL", "referenceIds": ["r3"] }
                    ],
                    "linkedOrganizations": {
                        "org-1": {
                            "entityType": "ORGANIZATION",
                            "details": { "name": { "value": "Doe Nominees Pty Ltd" } }
                        }
                    },
                    "linkedIndividuals": {
                        "ind-1": {
                            "entityType": "INDIVIDUAL",
                            "name": { "givenName": "Jane", "familyName": "Doe" }
                        }
                    },
                    "typeInformation": {
                        "type": "DISCRETIONARY",
                        "discretionary": {
                            "appointors": [
                                { "entityId": "ind-1", "entityType": "INDIVIDUAL", "referenceIds": ["r3"] }
                            ],
                            "generalBeneficiaries": [
                                { "value": "The children of the settlor", "referenceIds": ["r4"] }
                            ]
                        }
                    }
                }
            },
            "references": {
                "r1": { "referenceId": "r1", "sourceId": "trust-deed", "location": { "page": 1 } },
                "r2": { "referenceId": "r2", "sourceId": "trust-deed", "location": { "page": 1 } }
            }
        }
    ]
}

If the trust type cannot be classified, type.detected is UNKNOWN and the trust details include the reasons under typeInformation.unknown. A trust type must be identified before the analysis can be confirmed.

Understanding the result

Field	What it tells you
`status`	The state of this analysis: `PROCESSING`, `FAILED`, `COMPLETE` (ready to review), or `CONFIRMED` (reviewed and accepted).
`documentInformation.trust.type`	The trust type. `detected` is what the analyzer classified from the deed; `provided` reflects a type you supplied ahead of time, if any.
`trustees`, `settlors`	The core trust roles. Each entry points to an entity in one of the `linked*` maps by its `entityId`.
`linkedIndividuals`, `linkedOrganizations`, `linkedUnknownEntities`	The extracted parties, keyed by id. A party that holds more than one role (for example, a settlor who is also an appointor) appears once here and is referenced from each role.
`typeInformation`	Type-specific detail, keyed by the trust type. See Supported Trust Types on the overview page.
`references`	Maps each extracted value back to where it was found in the deed, including the page number, so every field is traceable to its source.

Step 5: Confirm the Analysis

Confirmation is the human sign-off gate: it is how a reviewer accepts the extracted structure for compliance use. To correct any extracted field, send the corrected documentInformation (and any updated references) in the request body; to accept the analysis as-is, send it back unchanged. Confirmation records your accepted version while keeping the original analysis as an audit trail, so you always retain what the analyzer originally produced alongside what was approved. You can confirm again later if something needs to change: the latest confirmation becomes the valid one and earlier confirmations are superseded, while the original analysis stays in place. Confirm against the original analysis (the entry with status: COMPLETE) returned by Step 4.

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents/{{documentId}}/analyses/{{analysisId}}/confirm' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "documentInformation": {
        "type": "TRUST_DOCUMENT",
        "trust": {
            "name": { "value": "The Doe Family Trust" },
            "type": { "detected": "DISCRETIONARY" },
            "trustees": [ { "entityId": "org-1", "entityType": "ORGANIZATION" } ],
            "settlors": [ { "entityId": "ind-1", "entityType": "INDIVIDUAL" } ]
        }
    }
}'

{
    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}

Once confirmed, the workflow execution’s result moves from REVIEW to COMPLETE — the organization no longer reads as work in progress once a reviewer has signed off.

Step 6: Associate the Parties

With a confirmed analysis in hand, link the extracted parties to the focus organization through the relationships API. This attaches the trustees, settlors, beneficiaries, and other parties to the organization as individual and organization relationships, so the trust’s structure is represented on the entity and available to the rest of your KYB process.

Next Steps

Trust Analyzer overview — what the Trust Analyzer does, supported trust types, and FAQs.
Executing Workflows — how executionVariables are passed when executing a workflow.
Interpreting Workflow Results — parse the full workflowResult object.
Managing Organizations — create and manage the organization entity before running the workflow.
Anti-Money Laundering — screen the parties extracted from the trust deed.