{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"4582877a-2340-491c-81d9-063c5cebd945","name":"Legl Implementation - Engage - Individuals","description":"Legl's **Engage - Individuals** API is designed to give you all the tools needed to build an integration which allow firms to onboard clients and initiate compliance and AML processes such as ID verification, source of funds checks and document requests, with new and existing end clients.\n\nOur offerings allow simple, timely and efficient management of these processes.\n\nFor questions or queries, please contact [support@legl.com](https://mailto:support@legl.com).\n\nTo setup the API, please see the process [here.](https://help.legl.com/en/articles/483950-how-do-i-setup-legl-s-api)\n\nTo see operational and authentication information, please see the documentation [here.](https://api.legl.com/v1/docs/#section/Getting-Started/Authentication)\n\n# Key Concepts\n\n## **What is Engage?**\n\n**Engage** is Legl’s comprehensive tool for client onboarding, KYC, AML, and KYB which provides users across your firm with one connected workflow to seamlessly bring on new clients and store their important data. It brings together every stage of the client life-cycle - from onboarding, to due diligence, to ongoing monitoring and risk management.\n\nEngage also helps to make handoff between staff members straightforward and quick - from fee earners, to compliance staff, to practice management and all those in between, Legl's workflows ensure everyone can collaborate efficiently and stay on the same page.\n\nFor more information on Legl's Engage functionality, please see our [Help Center](https://help.legl.com/en/articles/119524-how-do-i-create-an-engage-request#h_469178db36).\n\n## What is a Workflow?\n\nA Workflow consists of a series of steps a firm needs to complete in order to achieve a particular outcome e.g. onboard a client. At Legl, workflows are used by law firms to streamline client onboarding and compliance processes - making it faster to take on new clients, and ensure risk is managerd consistently across departments.\n\nOnce one or more workflows are set up within a client's Legl account, the user can select their chosen workflow and send it to their client by creating an Engage Request, which will guide the client through each step they need to complete.\n\nClients configure and manage workflows via the user interface:\n\n\n\nA full list of Workflows (including those not available in the user interface, such as the Manual CDD workflow) can be viewed by querying listWorkflows or retrieveWorkflows.\n\nFor more information on Workflows, please see our [Help Center](https://help.legl.com/en/articles/119457-what-is-a-workflow).\n\n## **What is an Engage Request?**\n\nEngage Requests are objects containing a number of Steps for an end client to complete (e.g. ID check, and a request to upload a bank statement) packaged together following a Workflow template for what these Steps will be. Each Engage Request will be completed by an end client, as as it is completed, information about each of the steps e.g. the Date of Birth on their ID document, will be made available in the `steps` data of that Engage Request. As Legl generates PDF reports of the results, those reports become available via download links on the Engage request. A full list of Engage requests can be viewed by querying listEngageRequests or retrieveEngageRequest.\n\n\n\n## What is a Contact?\n\nA Contact is an object in Legl identifying an individual, as opposed to a Business.\n\n\n\nWhenever an Engage/Pay request is launched through the API or a Deep Link, Legl will attempt to identify a Contact in Legl (if it exists) to link the Engage Request to. A Contact will be created is there is no Contact which matches `email` AND `first_name` AND `last_name` attributes on the Engage Request.\n\nFor more information, please see our [Help Center](https://help.legl.com/en/articles/119484-what-are-contacts).\n\n# **What can I do with Legl's API for** Engage - Individuals **Integrations?**\n\nLegl's Engage - Individuals API facilitates integration patterns primarily with Practice Management and Case Management Systems (but these patterns are also used in Document Management Systems or even standalone platforms!).\n\nThe Engage - Individuals API allows clients to build flows which create or autopopulate Engage requests automatically. Once those Engage requests have been completed, the information returns to Practice/Case Management System automatically.\n\nThe full list of features available to implement for our Engage - Onboarding and - Ongoing Monitoring offerings is as follows:\n\n| Area | Offering | Capability | Description |\n| --- | --- | --- | --- |\n| Engage - Individuals | Onboarding and Risk | Deep Link to Legl Engage | Launches a pre-populated Engage Request in Legl for the user to fill out |\n| | | Generate Engage Request in Legl | Uses a custom user interface in the external to create an Engage request |\n| | | Engage Request Status Updates | As an Engage request progresses, updates are sent back from Legl to the external |\n| | | Review Engage Request | Allows user to review Engage in request in the external |\n| | | Document Upload on Engage Request completion | When an Engage request is Marked as Reviewed, any documents from the Engage request are uploaded back into the external |\n| | | Disburse per Engage Request Step | Create a disbursement to be billed back to the end client for Engage request Steps e.g. separate disbursements for an eSignature and for a Standard CDD step |\n| | | Disburse per Engage Workflow | Create a disbursement to be billed back to the end client per entire Engage request Workflow |\n| | Ongoing Monitoring | Status updates | Flag when there are new alerts to review |\n| | | Disable Ongoing Monitoring on an Individual | Ability to Disable Ongoing Monitoring from the external |\n\n# Onboarding and Risk\n\n## Deep Link into Legl - _initiate an Engage Request_\n\nDeep links are a way Legl allows users to launch Engage requests in Legl, pre-filling relevant information from an external platform to avoid double data entry and manual error, but allowing the user to select a Workflow and configure the request.\n\nYou can configure the following fields in the deep link with these query parameters:\n\n| **Parameter** | **Required** | Description |\n| --- | --- | --- |\n| `createmodal_show` | Yes | If this equals `true` or `True` the modal will be displayed on page load |\n| `createmodal_email` | Yes | Sets the Email Address field. Required so the Participant in ActionStep can link back to the Contact in Legl. If unavailable, ensure `createmodal_first_name` and `createmodal_last_name` are set. |\n| `createmodal_first_name` | Yes | Sets the First Name field on the modal. |\n| `createmodal_middle_name` | No | sets the Middle Names field |\n| `createmodal_last_name` | Yes | sets the Last Name field |\n| `createmodal_client_reference` | No | Sets the Client Reference field |\n| `createmodal_matter_reference` | Yes | Sets the Matter Reference field. Used to link Matter Id in ActionStep to the Engage request in Legl. |\n| `provider` | Yes | Should be set to the name of the external system. |\n\nThe below example incorporates these fields into HTML which can be used to launch an Engage request in Legl:\n\n``` html\nhttps://account.legl.com/engage/?createmodal_show=True&createmodal_email=john.doe@email.com&createmodal_first_name=John&createmodal_last_name=Doe&createmodal_middle_name=Persons&createmodal_matter_reference=MR001&createmodal_client_reference=CR001&provider=wonderfulPCMS\n\n ```\n\nWhen the link is clicked, an authentication screen should pop open and redirect the user to create an Engage request in the Legl platform, pre-populated with relevant details passed by the Deep Link.\n\n\n\nThe Contact will receive the following request asking them to fill out any Workflow steps inserted into an [Engage Workflow](https://help.legl.com/en/articles/119457-what-is-a-workflow).\n\n\n\nFor information on how to track these Engage requests once sent, see the Status Updates section below.\n\n## Generate Engage request in Legl - _initiate an Engage Request_\n\nThis method allows teams to initiate Engage requests within a custom user interface in your system, and without needing to have user permissions in Legl themselves. You can create a UI component which allows the user to send [this](https://luke-dailey-legl-6333492.postman.co/workspace/Personal-Workspace~43ca3cb8-43fe-4fa8-964b-db552d6475ba/request/47604309-2d491488-0ab8-47c4-b168-edf699e91de2?action=share&source=copy-link&creator=47604309&ctx=documentation) API request to createEngageRequest in Legl, specifying a Workflow and information in the `client_information` attribute to match to an existing Contact (see above What is a Contact? for more information). See the following screenshot of some user interface in our ShareDo integration which has this component:\n\n\n\nWhen sent this request will create an Engage request and, optionally, send an email directly to the email sent in the request payload `email` attribute. The response will contain the `submit_url` attribute which, when followed, allows the end user to go through the following Workflow steps inserted into the [Engage Workflow](https://help.legl.com/en/articles/119457-what-is-a-workflow).\n\n\n\nYou can get a list of available Reviewers to populate `assigned_reviewer_email` in the createEngageRequest endpoint by using the [getReviewers](https://legl-dev.postman.co/workspace/Legl~1fdf434d-8798-47d7-8140-0ccd206222e9/request/48173478-7b9badd4-be99-4db1-9b62-1e493f2eb2f8?action=share&source=copy-link&creator=48173478&ctx=documentation) request.\n\n## Engage Request Status Updates\n\nThere are a number of stages an Engage request passes through when it has been sent off to the Contact. These can be incorporated into your system by querying the listEngageRequests endpoint, or receiving webhooks (on request from [support@legl.com](https://mailto:support@legl.com) - please specify the endpoint these requests should be sent to, and ensure an Admin user from the Firm has approved in writing).\n\nFor each of these Status updates, the `status` field in the below Engage Request:\n\n``` json\n{\n\"url\": \"http://example.com\",\n\"submit_url\": \"http://example.com\",\n\"reference\": \"string\",\n\"flow_name\": \"string\",\n\"first_name\": \"string\",\n\"last_name\": \"string\",\n\"email\": \"string\",\n\"client_reference\": \"string\",\n\"matter_reference\": \"string\",\n\"steps\": [],\n\"created_date\": \"2019-08-24T14:15:22Z\",\n\"completed_date\": \"2019-08-24T14:15:22Z\",\n\"reviewed_date\": \"2019-08-24T14:15:22Z\",\n\"completed_redirect_url\": \"http://example.com\",\n\"view_url\": \"http://example.com\",\n\"status\": \"Created\",\n\"hidden_reference\": \"string\"\n}\n\n ```\n\nand the same `status` field on a webhook:\n\n``` json\n{\n\"uuid\": \"095be615-a8ad-4c33-8e9c-c7612fbf6c9f\",\n\"created_at\": \"2019-08-24T14:15:22Z\",\n\"version\": 1,\n\"event_type\": \"engage_request_submitted\",\n\"data\": {\n\"url\": \"http://example.com\",\n\"submit_url\": \"http://example.com\",\n\"reference\": \"string\",\n\"flow_name\": \"string\",\n\"first_name\": \"string\",\n\"last_name\": \"string\",\n\"email\": \"string\",\n\"client_reference\": \"string\",\n\"matter_reference\": \"string\",\n\"steps\": [],\n\"created_date\": \"2019-08-24T14:15:22Z\",\n\"completed_date\": \"2019-08-24T14:15:22Z\",\n\"reviewed_date\": \"2019-08-24T14:15:22Z\",\n\"completed_redirect_url\": \"http://example.com\",\n\"view_url\": \"http://example.com\",\n\"status\": \"Created\",\n\"hidden_reference\": \"string\"\n}\n}\n\n ```\n\nwill change to the relevant status.\n\n### Sent\n\nThe Engage request has been created in Legl, and Sent to the Contact. The Contact has not submitted any information yet. In Legl, the Engage request looks like this in Legl:\n\n\n\n### Ready for Review\n\nOnce the Contact completes the Engage request by submitting the requested information, the `status` will update to `Ready for review`.The Engage request is ready to be reviewed and signed off in Legl once the responsible fee earner/risk officer has examined the results of the Legl checks.\n\n\n\n### Reviewed\n\nOnce the fee earner/risk officer has reviewed the request and approved it, the `status` will update to `Reviewed`. The Engage request is effectively closed and any automations can be picked up on the side of your systems, for example, collecting CDD documents to store in a central document repository or creation of a disbursement.\n\n\n\n### Further Information on Status Webhooks\n\nPlease see the [schema accompanying](https://api.legl.com/v1/docs/#tag/Engage-Endpoints/operation/engage_requests_create) this webhook definition, which provides more detail on the meaning and content of each of the attributes in the webhook.\n\n## Review Engage Request\n\nEngage Requests are typically Marked as Reviewed from the user interface by the fee earner responsible for the Matter it relates to.\n\nIt is also possible to mark these Engage requests as Reviewed via the API by calling the markEngageRequestReviewed endpoint as shown [here](https://legl-dev.postman.co/workspace/1fdf434d-8798-47d7-8140-0ccd206222e9/request/48173478-5dcbc5c3-7efc-4955-8e34-8f8fc9db5ecb?action=share&source=copy-link&creator=48173478&ctx=documentation).\n\nThe `reviewer_email` attribute acts as an audit log identifying which user should be shown to have marked the Engage request as reviewed.\n\nThe `reviewer_comment` will display a comment as if a user had left a comment on the Engage request.\n\n\n\n\n\n## Document Upload on Engage Request completion\n\nIt is possible to download any documents filled out by the end Client as part of an Engage request, from the point the Engage request is 'Ready for Review' status, but more commonly after the Engage request is 'Reviewed' status. The URLs to call to download the file for a particular step can be found under the `steps.results_document_url` attribute on each Engage request called via the listEngageRequests or retrieveEngageRequest endpoint:\n\n``` json\n\"steps\": [\n {\n \"type\": \"source-of-funds\",\n \"results_document_url\": \"https://api.legl.com/v1/engage_requests/download_step_file/5293382\",\n \"results_pdf_url\": \"https://api.legl.com/v1/engage_requests/download_step_file/5293382\"\n }\n]\n\n ```\n\nThe folllowing step `types`s will have this attribute which can be used to download the results PDF:\n\n- `cdd`\n \n- `custom-form`\n \n- `source-of-funds`\n \n- `signature-request`\n \n- `document-request`\n \n- `proof-of-address`\n \n\nPlease see the FAQ below \"Which steps are available in an Engage Request?\" for an explanation on what kinds of steps can be defined in an Engage Request using the `steps.type` attribute.\n\n# Disbursements\n\nDisbursements allow the costs of Legl checks to be passed onto end clients. This is functionality which is typically implemented in a Practice Management System (for example, as part of Legl's native ActionStep integration).\n\nA disbursement may look like the following in your Practice Management System:\n\n\n\nThe disbursement above passes on the cost of a Legl 'cdd' step type, to the end client. This has been priced at £20.00 by the owner of the integration - the cost of the disbursement will be set entirely by the firm, taking into account their billing setup.\n\nLegl's API does not contain the concept of a 'disbursement', but does have a number of tools which can help you to create disbursements in your own systems.\n\n## Disburse per Engage Workflow\n\nWhen an Engage Request moves to the 'Reviewed' status, this is typically the point at which a firm may bill the end client for the cost of the individual steps in the Workflow (see Workflows above under Key Concepts).\n\nOne way to do this is decide on how much each Workflow should cost, and when you receive an Engage Request Status Update, use the `flow_name` attribute to decide the cost of the Engage Request, and the `client_reference, matter_reference`attributes to decide where the disbursement should be placed in your system.\n\n## Disburse per Engage Step\n\nIf you wish to set disbursements per Workflow _step,_ this can be implemented dynamically by querying the Workflow underlying the Engage Request Status Update by using the `flow_name` atrribute in the Engage Request, to query the `listWorkflows` endpoint using the `name` attribute.\n\nThe `steps` list attribute for each Workflow will allow you to check which steps make up the Workflow, and disburse for any you decide need to be passed onto the end client in line with your firm's risk policies.\n\n# Ongoing Monitoring\n\nOnce an Engage request has been reviewed, Legl is able to monitor the status of AML compliance on the Contact, and notify users if AML compliance state has changed. For more information on this feature, and the circumstances in which it will be turned on when an Engage request is completed, see our [Help Center](https://help.legl.com/en/articles/119469-how-do-i-use-ongoing-monitoring-for-individual-clients).\n\nThere are three ways in which Ongoing Monitoring can be integrated:\n\n1. **Ongoing Monitoring Status Change**: Status updates from webhooks which inform your systems when Ongoing Monitoring is turned On or Off for a particular Contact, whether through the user interface or through the API.\n \n2. **Ongoing Monitoring Alerts**: Status updates from webhooks which inform your systems when an alert has been received for Ongoing Monitoring on a particular Contact, changing the potential AML risk of that Contact, and when alerts have been completely reviewed via the user interface.\n \n3. **Disable Ongoing Monitoring**: Ongoing Monitoring is turned on by default for a Contact when a first PEPs and Sanctions report is run via [Watchlist Screening](https://help.legl.com/en/articles/5520153-how-to-run-an-in-person-cdd-check-when-meeting-your-client), [Instant Screening](https://help.legl.com/en/articles/5520153-how-to-run-an-in-person-cdd-check-when-meeting-your-client), or via a [Standard or Basic CDD workflow](https://help.legl.com/en/articles/4757145-getting-started-guide-for-legl-workflow-users) which can be triggered via the API (see Generate Engage request in Legl and Deep Link into legl above).\n \n\nWebhooks are configured on request by emailing [support@legl.com](https://mailto:support@legl.com) - please specify the endpoint these requests should be sent to, and ensure an Admin user from the Firm has approved in writing\n\n## How should I use Entity UUID?\n\nReceiving alerts for, and disabling Ongoing Monitoring, requires use of the `entity_uuid`. This is a unique identifier relating to a Contact.\n\nThis identifier can be retrieved and mapped to your internal systems by querying the the listEngageRequests, retrieveEngageRequest or createEngageRequest endpoints with the `include_entity=true` query parameter.\n\nThe `entity_uuid` corresponds to the `entity_uuid` field included by using the `include_entity:true` query parameter in your request when querying the following endpoints :\n\n- `createEngageRequest`\n \n- `listEngageRequests`\n \n- `retrieveEngageRequest`\n \n- `createBusiness`\n \n- `retrieveBusiness`\n \n- `disableOngoingMonitoring`\n \n\nOr on receiving one of the following webhooks:\n\n- `\\\\\\\\\\\\\\\\\\\\\\*.configuration_changed`\n \n- `\\\\\\\\\\\\\\\\\\\\\\*.alert_status_changed`\n \n\nOngoing Monitoring for Business entities is avaiulable, but not in the scope of this guide.\n\n## Status Updates\n\n**Ongoing Monitoring Status Change:**\n\nWhen Ongoing Monitoring is `disabled` or `enabled` which can be done via the API (see below Disable Ongoing Monitoring) or via the User Interface from the Contacts screen, a webhook can be sent to a specified endpoint:\n\n\n\n\n\nThe webhook looks as follows. `current_status` will be either `disabled` or `enabled` depending on whether Ongoing Monitoring has been turned On or Off.\n\n``` json\n{\n \"uuid\": \"095be615-a8ad-4c33-8e9c-c7612fbf6c9f\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"version\": 1,\n \"event_type\": \"individual_watchlist_monitoring.configuration_changed\",\n \"data\": {\n \"entity\": {\n \"type\": \"individual\",\n \"entity_uuid\": \"ccd0bbaa-1979-4620-9054-a91c61d70e41\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"middle_name\": \"string\",\n \"email\": \"user@example.com\",\n \"date_of_birth\": \"2019-08-24\",\n \"client_reference\": \"string\"\n },\n \"current_status\": \"disabled\"\n }\n}\n\n ```\n\n**Ongoing Monitoring Alerts:**\n\nWhen Ongoing Monitoring detects an alert for a Contact, it can send a webhook to a specified endpoint which allows your system to link back to the Contact for a user to review those alerts. The notification will look like so:\n\n``` json\n{\n \"uuid\": \"095be615-a8ad-4c33-8e9c-c7612fbf6c9f\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"version\": 1,\n \"event_type\": \"individual_watchlist_monitoring.alert_status_changed\",\n \"data\": {\n \"entity\": {\n \"type\": \"individual\",\n \"entity_uuid\": \"ccd0bbaa-1979-4620-9054-a91c61d70e41\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"middle_name\": \"string\",\n \"email\": \"user@example.com\",\n \"date_of_birth\": \"2019-08-24\",\n \"client_reference\": \"string\"\n },\n \"current_status\": \"action_required\",\n \"url\": \"http://example.com\"\n }\n}\n\n ```\n\nThe `current_status` attribute will be set to either: `no_action` or `action_required` depending on whether new alerts have been registered against the Contact to review, or all alerts have been cleared and reviewed.\n\nTypically, customers will use the URL in the `url` attribute, which links to the Contact in Legl, to allow users to click-through and review these alerts in the Legl platform from the relevant Contact page. See our [Help Center](https://help.legl.com/en/articles/119469-how-do-i-use-ongoing-monitoring-for-individual-clients) for more information on how to review these alerts in Legl.\n\n## Disable Ongoing Monitoring\n\nYou can disable Ongoing Monitoring from your system for a particular Contact by using `entity_uuid` as a query parameter and sending the [Disable Ongoing Monitoring](https://legl-dev.postman.co/workspace/1fdf434d-8798-47d7-8140-0ccd206222e9/request/48173478-7103d256-a4c9-42b7-9626-f65a371b728e?action=share&source=copy-link&creator=48173478&ctx=documentation) request to Legl.\n\nFor Individual entities, turn off monitoring by passing an empty array in the `monitoring_to_disable` payload: `[]`\n\nOngoing Monitoring for Business entities is avaiulable, but not in the scope of this guide.\n\n# FAQs\n\n## Which steps are available in an Engage Request?\n\n| **User interface Step name** | **Supported?** | **API Step** **`type`** | **Description** |\n| --- | --- | --- | --- |\n| CDD Report | Yes | `cdd` | Verify an individual's identity with a range of different types of Client Due Diligence checks. This step will contain a download link in the `results_document_url`attribute. See below \"How do I use CDD Step Data?\" for information on the other information available for this `step.type.` |\n| Source of Funds | Yes | `source-of-funds` | Collect information on any sources of funds for an individual. This step will contain a download link for the Source of Funds report in the `results_document_url` attribute. See below \"How do I use Source of Funds Data?\" for information on the other information available for this `step.type.` |\n| Request a document | Yes | `document-request` | Request a document from the end client. This step will contain a download link for the document uploaded by the customer in the `results_document_url` attribute. |\n| Request signature(s) | Partial | `signature-request` | Request signature from an end client for a document uploaded to the Engage Request. Documents for signature can only be uploaded via the user interface, so Engage Requests with this step cannot be created via the \"Generate Engage request in Legl\" feature for AML Checks. Instead they have to be created with the \"Deep Link to Legl Engage Request\" feature for AML Checks. |\n| Customisable form | Yes | `custom-form` | Used by firms to request additional information from clients. This step will contain a download link for the document uploaded by the customer in the `results_document_url` attribute. |\n| Send a document | No | `N/A` | This step is not supported via the API and will not appear in Engage Request `steps` information. The document(s) uploaded for this step in the user interface will be known to and under the control of the firm in any case, and this is unlikely to contain useful information as a step in an Engage Request. |\n| Payment request | Partial | `N/A` | This step does not appear in the Engage Request object via the API, instead the Engage Request will be identified by querying the `listPayments` endpoint (though this implementation is out of scope for this guide). |\n| Proof of Address | Yes | `proof-of-address` | This step contains independent `proof-of-address` verification if proof of address is run independently of a any CDD step. If the proof of address is run in conjunction with a CDD steop, the verification will be in the `cdd` step type. |\n\nFor more information on the functional use cases for each of the Steps, please see our [Help Center](https://help.legl.com/en/articles/257411-legl-workflow-templates).\n\n## How do I use Source of Funds Data?\n\nPlease see the following description for each field in Source of Funds `results_data`,\n\nwhich contains an array of `sources` as an attribute, each of which will contain the following fields:\n\n| Field | Description |\n| --- | --- |\n| **`type`** | The category of source of funds. Values: `\"gift\"`,`\"inheritance\"`, `\"investments-sale\"`, `\"loan\"`, `\"other\"`, `\"property-sale\"`, `\"remortgage\"`, `\"mortgage\"`, `\"savings\"` |\n| **`amount`** | The two decimal point float value of this source of funds (e.g., \"5000.00\"). How much money is coming from this source. Currency is not exposed, but will be dictated by the currency settings on your Firm. |\n| **`comment`** | Lawyer/reviewer comments on the source (internal note field, not client-facing). |\n| **`description`** | Free-text explanation of the source. Used when `source.type` is `\"other\"`, `\"investments-sale\"` or `\"inheritance\"`\\- prompts the client: \"Please explain how you earn your income\" |\n| **`income_source`** | **Savings-specific field**. For `source.type: \"savings\"`, indicates how the client earns their income. Values: \"employment\", \"self-employed\", \"retired\", \"other\". If the `source.type is not \"savings\"` , this will be `null` . |\n| **`name`** | Name associated with the source (e.g., name of person giving a gift, loan provider name) |\n| **`is_received`** | Boolean. Has the client already received this money? `true` = already received, `false` = expected/pending. |\n| **`salary`** | **Savings + Employment only**. Annual salary amount when `income_source: \"employment\"`. Prompts the client to provide \"Annual Salary\" |\n| **`appears_on_statement_as`** | Applicable to`source.type: \"savings\"` and `source.income_source: \"employment\"` only. How salary payments appear on the bank statement (e.g., employer name). UI label: \"How does this payment appear on your statement?\" |\n| **`is_pension_claimed`** | Applicable to`source.type: \"savings\"` and `source.income_source: \"retired\"`. Boolean. Does the client claim a pension?. Prompts the client to answer: \"Do you claim a pension?\" |\n| **`pension_provider`** | Applicable to`source.type: \"savings\"` and `source.income_source: \"retired\"` and `is_pension_claimed:true`. Name of the pension provider. Prompts the client to answer: \"Who is your pension provider?\" |\n| **`pension_start`** | Applicable to`source.type: \"savings\"` and `source.income_source: \"retired\"` and `is_pension_claimed:true`. Date when client started claiming pension. Prompts the client to answer: \"When did you start claiming your pension?\" |\n| **`pension_frequency`** | Applicable to`source.type: \"savings\"` and `source.income_source: \"retired\"` and `is_pension_claimed:true`. How often pension is paid. Values: \"weekly\", \"monthly\", \"other\". Prompts the client to answer: \"How frequently is your pension paid?\" |\n| **`addresses`** | Array of related addresses (e.g., `third_party`, `property`, `solicitor`) |\n| **`overseas_funds`** | Boolean. Are these funds coming from overseas? `true` = foreign source, `false` = domestic |\n\nSee the example request for [EngageRequestSourceofFunds](https://legl-dev.postman.co/workspace/1fdf434d-8798-47d7-8140-0ccd206222e9/example/48173478-e8df8235-4c80-430c-a295-ae79fa9e0c58?action=share&source=copy-link&creator=48173478&ctx=documentation) to see how multiple sources are represented in Source of Funds data.\n\n## How do I use CDD Step Data (including results_data)?\n\nThe results data in the Engage Request object accessible via `listEngageRequests` and `retrieveEngageRequest` is comprised of `client_information` which represents the information entered by the end client when filling out the Engage request.\n\nit also contains data on individual `\"result\"` _information, plus_ `\"overall_result\"` which will come back as `\"clear\"` if every individual result is also clear.\n\n``` json\n \"overall_result\": \"clear\",// This is an attribute that does not appear in the user interface\n \"id_data_validation_result\": \"clear\",\n \"identity_validation_result\": \"clear\",\n \"biometrics_result\": \"clear\",\n \"peps_and_sanctions_result\": \"clear\",\n \"financial_checks_result\": \"clear\"\n\n ```\n\n`id_data_validation_details` is available when an ID document has been used as part of an Engage request containing CDD checks. It references the type of document used for ID validation, and the expiry date.\n\nIn the user interface, and in the accompanying PDF generated as part of an Engage request, the status of an Engage request looks like so, corresponding to the `clear` or `consider` results for each of the fields:\n\n- ID Data Validation: `\"id_data_validation_result\"`\n \n- Identity Validation: \"`identity_validation_result\"`\n \n- Biometrics: `\"biometrics_result\"`\n \n- Financial Screening: `\"financial_checks_result\"`\n \n- Watchlist Screening: `\"peps_and_sanctions_result\"`\n \n- `\"overall_result\"` **does not** exist in the user interface. This is calculated by reference to the other results, and only comes back with a `\"clear\"` result if all other attributes are also `\"clear\"`, otherwise it will be `\"consider\"`.\n \n\n\n\n\n\n`client_information` contains information about the end client which the end client has confirmed as part of the Engage request `basic-information` step:\n\n\n\n## What is a Manual CDD Check?\n\nA Manual CDD Check is a type of Workflow which is _only_ visible in the API, if it has been requested turned on for the firm you are working in.\n\nA manual CDD check has a`default` Workflow with the `url` attribute ”[https://api.legl.com/v1/workflows/manualcddworkflow](https://api.legl.com/v1/workflows/manualcddworkflow%E2%80%9D)\" available in your Legl platform. This new Workflow is only visible when querying the API via the `listWorkflows` or `retrieveWorkflow` endpoints. This manual CDD Workflow operates in the same way as the [in-person CDD check](https://help.legl.com/en/articles/119477-how-to-run-an-in-person-cdd-check) in the user interface, allowing you to run Financial Screenings and Watchlist Screenings against a Contact and retrieve the results in a resulting Engage request independently of an ID check i.e. no email is sent to the end client email included in the `createEngageRequest` payload.\n\n\n\nWhen creating an Engage request with this manual CDD workflow information just as with a different Engage Request, all 3 of `first_name`, `last_name` and `email` on the `createEngageRequest` payload must be an exact match for an existing [Contact](https://help.legl.com/en/articles/119484-what-are-contacts) in Legl to link the check to this record, or a new Contact will be created.\n\n## What is a Hidden Reference?\n\nA `hidden_reference` is a free field not used in the user interface, and kept reserved for integrators to use and store information against an Engage Request. Commonly it is used to store error handling information in a polling architecture, for example, if confirmation is needed from your middleware/external system when an Engage Request has been processed, simply fill the `hidden_reference` with a `processed` string on completion, or an `error` string with more detailed information on the error which occurred.\n\n## What is a Client Reference?\n\n`client_reference` is available on every Engage Request where a Contact (see above 'What is a Contact?' under Key Concepts), has a `client_reference` set on it. Currently it is possible to set a `client_reference` on _new_ Contacts created via the API, where Legl cannot find an exact match for the `first_name`, `last_name` and `email_address` attributes, a new Contact will be created with a corresponding `client_reference`. There is currently no way to update `client_reference` on an existing Contact, other than through the User Interface.\n\n`client_reference` should not be considered unique - Legl does not enforce uniqueness on `client_reference`.\n\n`client_reference` is also available as an attribute on Company Reports and Businesses, though these are out of scope for this guide.\n\n## What is a Matter Reference?\n\nA `matter_reference` is a reference which can be attributed to an Engage Request.\n\n`matter_reference` can also be found on Company Reports and Sanctions Reports.\n\nThese are non-unique references, intended to assist with querying via the API and linking Engage Requests to Matters in external systems.\n\n\n\n## Can I use Matter Reference Validation to enforce Firm Matter Reference Conventions?\n\nYes, please contact [support@legl.com](https://mailto:support@legl.com) if you wish to enable this feature.\n\nWe are able to enforce Matter Reference validation which means any Engage Requests created in the Legl User interface will need to conform to a Regex convention, e.g. must be 4 or 5 digits.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"48173478","team":5359039,"collectionId":"4582877a-2340-491c-81d9-063c5cebd945","publishedId":"2sBXVhDWfb","public":true,"publicUrl":"https://integrations.legl.com","privateUrl":"https://go.postman.co/documentation/48173478-4582877a-2340-491c-81d9-063c5cebd945","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2026-01-15T12:14:01.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/a7a2f4acf0f125bcd0455cd5cd2cdf4ab89335bf36faa55f00ae29ee35580e59","favicon":"https://legl.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://integrations.legl.com/view/metadata/2sBXVhDWfb"}