> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trust Analyzer Implementation
> Step-by-step API walkthrough for running a trust analysis: upload the deed, execute GLB-Trust-Analysis, retrieve and confirm the extracted structure, and associate the parties.
##### 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](/docs/kyb/trust-analyzer) 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](/docs/kyb/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.
```bash Request - Upload Trust Deed theme={null}
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.
```bash Request - Execute Trust Analysis Workflow theme={null}
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"
}
}'
```
```json Response - Execute Trust Analysis Workflow theme={null}
{
"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.
```bash Request - Retrieve Workflow Execution Result theme={null}
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.
```bash Request - Get Document Analyses theme={null}
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'
```
```json Response - Document Analyses (Discretionary trust) theme={null}
{
"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](/docs/kyb/trust-analyzer#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.
```bash Request - Confirm Analysis theme={null}
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" } ]
}
}
}'
```
```json Response - Confirm Analysis theme={null}
{
"requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}
```
### Step 6: Associate the Parties
With a confirmed analysis in hand, link the extracted parties to the focus organization through the [relationships API](/api-reference/organization-relationships/add-or-update-relationships-for-an-organization). 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](/docs/kyb/trust-analyzer) — what the Trust Analyzer does, supported trust types, and FAQs.
* [Executing Workflows](/docs/kyb/executing-workflows) — how `executionVariables` are passed when executing a workflow.
* [Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2) — parse the full `workflowResult` object.
* [Managing Organizations](/docs/kyb/managing-organizations) — create and manage the organization entity before running the workflow.
* [Anti-Money Laundering](/docs/kyb/anti-money-laundering) — screen the parties extracted from the trust deed.