--- title: "How do I configure an advanced reconciliation definition?" slug: "how-do-i-configure-an-advanced-reconciliation-definition" updated: 2026-10-22T14:59:08Z published: 2026-10-22T14:59:08Z canonical: "support.lusid.com/how-do-i-configure-an-advanced-reconciliation-definition" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I configure an advanced reconciliation definition? You can create a reconciliation (rec) definition to tell LUSID what data to compare and how to compare it. The definition specifies: - The portfolios on each side - The types of reconciliation to perform - The matching rulesets to apply - How the results are reviewed and approved **Recommended reading:** [Understanding advanced reconciliations](/v1/docs/advanced-reconciliations-1), [How do I create a matching ruleset?](/v1/docs/how-do-i-create-an-advanced-reconciliation-matching-ruleset) > [!WARNING] > Prerequisites > > Before getting started, ensure you have already created: > > - [x] The [portfolios](/v1/docs/portfolios), [portfolio groups](/v1/docs/what-is-a-portfolio-group), or [funds](/v1/docs/financial-reporting-abor) you want to reconcile > - [x] A [matching ruleset](/v1/docs/how-do-i-create-an-advanced-reconciliation-matching-ruleset) for each reconciliation type you want to include > - [x] A [recipe](/v1/docs/how-do-i-create-or-generate-a-recipe) for each side of the reconciliation ## Methods **LUSID web app** 1. Navigate to **Advanced Recs > Rec Definitions**. 2. Click the **Create rec definition** button and populate the form. Continue reading this article to learn more about the fields you can populate in a rec definition. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-3H239M0O.png?sv=2026-02-06&spr=https&st=2026-11-12T13%3A12%3A40Z&se=2026-11-12T14%3A12%3A40Z&sr=c&sp=r&sig=%2BVvug6sQOlx9N2jPgmic5EAkXJO8nsmfac4fUc3F53Y%3D) **LUSID API** ```json curl -X POST "https://.lusid.com/api/api/recs/definitions"  -H "Authorization: Bearer "  -H "Content-Type: application/json"  -d '{  "id": {    "scope": "Finbourne-Examples",    "code": "HoldingUnitsReconciliation"  },  "displayName": "Compare holding units",  "description": "Compares holding units between our records and the custodian'\''s records",  "sideNames": {    "left": "LUSID",    "right": "Custodian"  },  "details": {    "definitionType": "PortfolioContents",    "leftPortfolioSources": [      {        "sourceType": "Portfolio",        "id": { "scope": "Finbourne-Examples", "code": "EU" }      }    ],    "rightPortfolioSources": [      {        "sourceType": "Portfolio",        "id": { "scope": "Finbourne-Examples", "code": "EU-Custodian" }      }    ],    "rulesets": [      {        "recType": "Holding",        "matchingRulesetId": { "scope": "Finbourne-Examples", "code": "HoldingUnitsRule" }      }    ],    "valuationRecipes": {      "left": { "scope": "Finbourne-Examples", "code": "EU-Equities" },      "right": { "scope": "Finbourne-Examples", "code": "EU-Equities" }    },    "currencies": {      "left": "EUR",      "right": "EUR"    }  },  "reviewConfiguration": {    "openExceptions": { "reviewRequirement": "Required" },    "closedExceptions": { "reviewRequirement": "NotRequired" },    "matches": { "reviewRequirement": "NotRequired" },    "reviewSubmission": {      "completionRatioThreshold": 1.0,      "autoSubmit": false    },    "requiredApprovals": [      {        "approvalCode": "Desk",        "description": "Desk sign-off"      }    ]  } }' ``` ## Fields ### Definition type You must use the relevant type for the kind of data the rec definition compares. ### Sources The sources tell LUSID what data to compare on each side. For each side, you specify: - A side name to label each side in your results, for example `LUSID` or `Custodian`. - One or more portfolios, portfolio groups, or funds. > [!NOTE] > Using relational data for one side > > Instead of portfolios, portfolio groups, or funds, one side can use [relational data](/v1/docs/anatomy-of-a-dataset), for example a dataset loaded from a custodian. Only one side can use relational data. You don't choose the dataset in the reconciliation definition; you name it on each reconciliation type's [matching ruleset](/v1/docs/how-do-i-create-an-advanced-reconciliation-matching-ruleset) instead. Note: > > - Each matching ruleset must fit the kind of source on each side. > - If you change a side between portfolio data and relational data, you need to choose matching rulesets that fit the new sources. > - When you select **Relational data sources** in the web app, LUSID removes all the reconciliation types you've already added for that side, so choose your sources first. LUSID compares the same sources for each reconciliation type in the rec definition. ### Rec types and matching rulesets For each type of reconciliation you want to include in the definition, you must choose a [matching ruleset](/v1/docs/how-do-i-create-an-advanced-reconciliation-matching-ruleset) that decides how LUSID compares it. Note the following: - You can only include one of each rec type in the definition. - A matching ruleset must match both of the following: - The rec type. - The kind of source on each side (either portfolio data or relational data). If you can’t find a matching ruleset from the selector in the LUSID web app, check its [rec type](/v1/docs/how-do-i-create-an-advanced-reconciliation-matching-ruleset#reconciliation-type) is correct. If one side uses relational data, you can also add a [relational data filter](/v1/docs/filtering-information-retrieved-from-lusid) for each reconciliation type, for example `custodian eq 'MyCustodian'`. #### Valuation recipes and currencies For each side that uses portfolios, portfolio groups, or funds, you must specify a valuation recipe and a currency. Both are required, even if you're not reconciling valuations. > [!NOTE] > Note > > Neither field is required when the side uses relational data. ### Date policy Each time you run a reconciliation definition, LUSID creates a new instance. The date policy controls how each instance's dates relate to the previous instance, and what changes when you rerun an instance. > [!WARNING] > ⚠️ Warning > > You cannot change the date policy once the rec definition has an instance. Your date policy also decides two things you don't set directly: - **Rerun**: Whether you can rerun an instance. You can't rerun if both sides use `Explicit` [**As at dates**](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#as-at-dates), because nothing would change. - **Break ageing**: Whether LUSID tracks how long a break has stayed open across instances, so you can see which breaks are persistent. LUSID tracks it automatically when [**Effective date progression**](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#effective-date-progression) is `Series` and both sides use the `Latest` [**As at dates**](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#as-at-dates). #### Effective date progression When you create a rec instance, you set an effectiveAt date for the data you want to reconcile on each side. For example, LUSID compares the holdings each side has on that `effectiveAt` date. - **Series**: Both `effectiveAt` dates must be later than the previous instance's, so your instances form a timeline. - **Unconstrained**: Each instance can use any dates. > [!NOTE] > Note > > This does not apply to reruns. A rerun isn't a new instance; it keeps the instance's `effectiveAt` dates, and you can rerun an earlier instance in a series without affecting the instances after it. #### As at dates If your [**Effective date progression**](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#effective-date-progression) is set to `Unconstrained`, you can allow users to specify an [asAt](/v1/docs/what-is-the-asat-timestamp) date for each side when creating a new instance: - **Latest** (default): LUSID always uses the latest version of the data, including any corrections. This allows you to fix data and rerun to check your fixes. - **Explicit**: Set a specific asAt date when you create a new instance. #### **Activity window** Required for the following rec types and when [**Effective date progression**](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#effective-date-progression) is set to `Series`: - Input transactions - Output transactions - Settlement activity Currently, the only **Window type** option is `Contiguous`. This means each instance covers the activity since the previous instance’s effective date, so there are no gaps or overlaps. > [!NOTE] > Note > > A rerun of an instance maintains the same window. The following table shows you how you could configure various example use cases: | Use case | Effective date progression | As at dates | Activity window | Allows reruns? | Allows break ageing? | | --- | --- | --- | --- | --- | --- | | A recurring reconciliation, such as daily holdings | `Series` | `Latest` on both sides | None | ✅ | ✅ | | A recurring reconciliation of transactions or settlement activity | `Series` | `Latest` on both sides | `Contiguous` | ✅ | ✅ | | A one-off check against current data | `Unconstrained` | `Latest` on both sides | None | ✅ | ❌ | | A one-off check against a fixed baseline. Fix data on the live side and rerun to check the effect. | `Unconstrained` | `Latest` on one side, `Explicit` on the other | None | ✅ | ❌ | | An investigation of data as it was known at a past point in time | `Unconstrained` | `Explicit` on both sides | None | ❌ | ❌ | ### Review and approval #### Results review You can specify which [types of results](/v1/docs/understanding-advanced-reconciliations-results) require review: - **Open exceptions:** Breaks, partial matches, and partial crosses that aren't resolved - **Closed exceptions:** Exceptions that were accepted, force matched, or cleared on a rerun - **Matches:** Matches and crosses You can add a condition for each type of result using [LUSID filtering syntax](/v1/docs/filtering-information-retrieved-from-lusid) to exclude certain results from your **Review** requirement setting. #### Review submission You can set a **Minimum review completion** percentage, so that: - A reviewer can't submit a result set until enough results are reviewed. - If enabled, LUSID automatically submits for approval once the percentage is reached. #### Required approvals If a result set needs sign-off, you can add a required approval for each one, for example `Desk` and `Risk`. Every approval must come from a different user. You can restrict who gives each approval using approver criteria such as: - `id`: The user’s [ID](/v1/docs/what-is-a-user-id-and-how-do-i-discover-one). - `type`: The user’s [account type](/v1/docs/how-do-i-set-up-a-personal-user-account), for example `Personal`. - `role.scope` and `role.code`: The scope and code of a [role](/v1/docs/what-is-a-role) assigned to the user. For example, `role.code eq 'RiskApprover'` allows any user with the `RiskApprover` role to give the approval. Leave the criteria blank to allow any user to give approval. For more information on how review and approval works, see [Understanding result sets in advanced reconciliations](/v1/docs/understanding-advanced-reconciliations-result-sets). ## Updating a rec definition Once created, you can update a rec definition via: - **LUSID web app**: Find the definition in the **Rec Definitions** dashboard and click the **Edit** icon. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-D04Y7CKN.png?sv=2026-02-06&spr=https&st=2026-11-12T13%3A12%3A40Z&se=2026-11-12T14%3A12%3A40Z&sr=c&sp=r&sig=%2BVvug6sQOlx9N2jPgmic5EAkXJO8nsmfac4fUc3F53Y%3D) - **LUSID API**: Call the [UpdateRecDefinition API](https://www.lusid.com/docs/api/lusid/endpoints/recs/UpdateRecDefinition). Note this replaces the whole definition; any omitted fields are set to null. Note that you cannot update the following: - The rec definition’s scope and code - [Definition type](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#definition-type) - [Date policy](/v1/docs/how-do-i-configure-an-advanced-reconciliation-definition#date-policy) (unless the rec definition has never created an instance) A recipe is a hierarchical, modular set of rules that govern numerous LUSID operations. A recipe configures conditional pricing models, aggregation, where to source market data from, fallback rules, and much more. For bitemporal data, the **effectiveAt** timestamp reflects the point in time at which a data item becomes valid in LUSID from a business perspective. You can specify the field when you make a read or update request to LUSID, indicating that you want to retrieve or update data that is effective at the specified date. For bitemporal data, the **asAt** timestamp reflects the point in time at which a data item is saved into LUSID. This allows data to be extracted from LUSID as it was at a point in the past, regardless of any subsequent updates or corrections. It is determined internally by LUSID and cannot be updated by the user.