Skip to main content
Preview feature
The Trust Analyzer is available through the API today. Portal screens for running, reviewing, and confirming a trust analysis are still being built, so drive the flow through the API for now. The endpoints below are stable, but response details may still change as the feature is finalised.
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 API walkthrough. This guide walks the full lifecycle: upload the deed, run the workflow, retrieve the extracted structure, confirm it, and link the parties to the organization. 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, 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"
    }
}'
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'
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

FieldWhat it tells you
statusThe state of this analysis: PROCESSING, FAILED, COMPLETE (ready to review), or CONFIRMED (reviewed and accepted).
documentInformation.trust.typeThe trust type. detected is what the analyzer classified from the deed; provided reflects a type you supplied ahead of time, if any.
trustees, settlorsThe core trust roles. Each entry points to an entity in one of the linked* maps by its entityId.
linkedIndividuals, linkedOrganizations, linkedUnknownEntitiesThe 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.
typeInformationType-specific detail, keyed by the trust type. See Supported Trust Types on the overview page.
referencesMaps 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" } ]
        }
    }
}'

​
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