# Create an API Token Source: https://developer.mindbridge.ai/api-explorer/create-api-token ## Go to the API tab **Note:** Only App Admins can access the API tab. Learn about user roles. 1. Select **Admin** (Admin icon) near the bottom of the MindBridge sidebar on the left side of the screen. You will go to the User Management tab in the Admin settings by default. 2. Go to the **API** tab. You will see a list of API tokens created by your team (if any exist). ## Create a new API token 1. Select **Create token** (located near the top-right corner of the page). You will go to the token creation page. 2. During token creation, provide the following details: * **Name (required):** Enter a unique name for the API token. * **Expiration (required):** Use the menu to choose when the token should expire. * **Permissions (required):** Check the boxes next to the permissions users should have for each endpoint.\ **Note:** The API reference documentation linked on the API tab provides details about each request's basic body and schema. * **Allow list (recommended):** Enter IP address(es) or CIDR that will be allowed to access the MindBridge API. If no restrictions are specified, then no filtering will be applied. 3. When you are satisfied, select **Create token** (located at the bottom-right corner of the page). You will be notified of the token creation status and provided a token ID number to access the MindBridge API. 4. Copy the API token and store it in a secure location. The API token can only be viewed and copied once and cannot be reproduced. If the token number is lost or the token settings need updating, you must create a new token. A given token will remain active until the expiry date, or until it is manually deleted. **Note:** The security of your generated token is paramount, and much like your personal passwords, should never be shared. If a token is compromised, the token must be disabled and re-issued immediately. # Endpoint model Source: https://developer.mindbridge.ai/api-explorer/endpoint-model Endpoints are structured in a standard way: ### Create `POST /{entityName}` - Creates an entity with the properties specified in the request body. ### Read `GET /{entityName}/{entityId}` – Reads the entity identified by the ID. ### Update `PUT /{entityName}/{entityId}` – Updates the entity identified by the ID with the content of the request body. Every time an entity is saved, the `version` property is incremented. To prevent multiple calls from overwriting each other's changes, the `version` property in the updated request body must match the latest version on MindBridge's servers. ### Delete `DELETE /{entityName}/{entityId}` – Deletes the entity identified by the ID. ### Query `POST /{entityName}/query` – Performs a paged query of the entity collection. # Entity model Source: https://developer.mindbridge.ai/api-explorer/entity-model All endpoint requests and responses for a given entity use the same model structure, with some fields being either read-only or editable depending on the method. If a property is not editable for the endpoint in question, it will be ignored. For example, if the following organization entity body is used with the `Create Organization` endpoint, then the `id` property will be ignored and a new organization will be created with a new id and "New organization" as the name. ```json theme={null} { "id": "4b8360d00000000000000001", "name": "New organization" } ``` Using this approach, an entity can be created or updated using the same model read from a read entity call, as read-only fields will not be overwritten by changes made to the *create* or *update* body. If a property that is not present on the model is included in a create or update request, then the request body will be considered invalid and an error will be returned. # Export Source: https://developer.mindbridge.ai/api-explorer/export-open-api-specification # Overview Source: https://developer.mindbridge.ai/api-explorer/info-description The MindBridge API is an HTTP REST API that provides access to MindBridge entities and processes. Request and response bodies are generally JSON formatted, with some exceptions. # MindBridge Query Language Source: https://developer.mindbridge.ai/api-explorer/mindbridge-query-language ### Overview MindBridge Query Language (QL) is the standard unified query language used to interact with all the underlying data tables and collections within MindBridge. This query language has been extended to the MindBridge API, which uses this syntax for all `/query` endpoints within the API, as well as several other endpoints. ### Syntax The query is expressed as a JSON object. The example below looks for values equal to 10000 in the `credit` column. ```json theme={null} { "credit": { "$eq": 10000 } } ``` Above, `$eq` is the equality operator. Other operators are listed below. As a shortcut for equality, you can specify the value directly. ```json theme={null} { "credit": 10000 } ``` In order to conform to the syntax of a valid JSON object, all operators and fields must be enclosed in quotes. For more details on the JSON language, refer to [json.org](https://json.org). Logical `AND` and `OR` conditions are available. If you want to specify two columns, the conditions can be combined with `$and`. ```json theme={null} { "$and": [ { "account": { "$eq": "1023345" } }, { "risk": { "$gte": 5000 } } ] } ``` #### Simplified Syntax The example `$and` query above can be simplified using the syntax seen below. ```json theme={null} { "account": { "$eq": "1023345" }, "risk": { "$gte": 5000 } } ``` You can combine `$or` and `$and` to build up a more complex structure, such as the one seen below, which combines all the techniques seen so far. ```json theme={null} { "risk": { "$gte": 5000, "$lt": 7000 }, "$or": [ { "transaction": { "$iprefix": "ABC1" } }, { "transaction": { "$iprefix": "ABC2" } } ], "$and": [ { "source": { "$ne": "MA" } }, { "source": { "$iprefix": "M" } } ] } ``` You can use two operators on the same column at the same time: ```json theme={null} { "credit": { "$gte": 1000, "$lt": 10000 } } ``` #### Unique Names Every field in a JSON object or sub-object must be **unique**. The following is not valid because `source` appears twice at the top level. ```json theme={null} { "source": { "$ne": "MA" }, "source": { "$ne": "MB" } } ``` Instead, wrap it in `$and`: ```json theme={null} { "$and": [ { "source": { "$ne": "MA" } }, { "source": { "$ne": "MB" } } ] } ``` Or use another operator like `$nin`: ```json theme={null} { "source": { "$nin": [ "MA", "MB" ] } } ``` You can use two operators on the same column at the same time: ```json theme={null} { "credit": { "$gte": 1000, "$lt": 10000 } } ``` ### Column Operators **Column operators** apply a filter to a specific column. | Description | Description | Column Types | Field Conditions | | - | - | - | - | | `$eq` | Tests if the value in the column **is identical** to the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`equalitySearch` must be true | | `$ne` | Tests if the value in the column **is not identical** to the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`equalitySearch` must be true | | `$gt` | Tests if the value in the column is **greater than** the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`rangeSearch` must be true | | `$gte` | Tests if the value in the column is **greater than or equal** to the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`rangeSearch` must be true | | `$lt` | Tests if the value in the column is **less than** the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`rangeSearch` must be true | | `$lte` | Tests if the value in the column is **less than or equal** to the literal value. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`rangeSearch` must be true | | `$contains` | Tests if an array **contains** a literal value.
For example, given a transaction with entries from accounts 12345 and 23456, the following query on the `gl_journal_tx` data table would match the transaction:
`{ "accounts": { "$contains": "12345" } }` | ARRAY\_STRINGS | case-insensitive on STRING values
`containsSearch` must be true | | `$ncontains` | Tests if an array **does not contain** a literal value. | ARRAY\_STRINGS | case-insensitive on STRING values
`containsSearch` must be true | | `$in` | Tests if a column is equal to one of the values in an array of literals. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`equalitySearch` must be true | | `$nin` | Tests if a column is **not equal** to any values in an array of literals. | STRING
DATE\_TIME
INT32
INT64
FLOAT32
FLOAT64
MONEY\_100
PERCENTAGE\_FIXED\_POINT
OBJECT\_ID | case-insensitive on STRING values
`equalitySearch` must be true | | `$flags` | Accepts an object with one or more keys with boolean values. Tests if the flags (keys) match the values.
For example, to search for entries that triggered the [2 Digit Benford](https://support.mindbridge.ai/hc/en-us/articles/360056059834) control point, use this query on the `gl_journal_lines` data table.
`{ "cp_failed": {"$flags": { "journal_entry_two_digit_benford": true }}}` | BOOLEAN\_FLAGS | | | `$isubstr` | Tests if a literal value **matches** the value in the column. For example, the following query on the `engagements/query`
endpoint will match engagements named "abc", "aBc", and "zabcd".
`{ "name": { "$isubstr": "abc" } }` | STRING | case-insensitive on STRING values
`allowCaseInsensitiveSubstringSearch` must be true | | `$iprefix` | Tests if a literal value **matches** the start of the value in the column. For example, the following query on the `gl_journal_tx` data table will match transactions "T1234", "t1234", and "T12345".
`{ "transaction": { "$iprefix": "T1234" } }` | STRING | case-insensitive on STRING values
`caseInsensitivePrefixSearch` must be true | | `$niprefix` | Tests if a literal value **does not match** the start of the value in the column. | STRING | case-insensitive on STRING values
`caseInsensitivePrefixSearch` must be true | ### Root Operators #### Logical Operators **Logical operators** allow MindBridge to combine Column Operation queries to allow for more sophisticated calls. | Operator | Description | | - | - | | `$and` | Tests that **all** contained terms are evaluated to be `true`. | | `$or` | Tests that **any** contained terms are evaluated to be `true`. | #### Keyword Operators **Keyword operators** are applied simultaneously to all columns that support keyword searches. This is controlled by the keywordSearch attribute associated with the column’s metadata. | Operator | Description | | - | - | | `$keyword_prefix` | Performs a case-insensitive prefix search of all words in the row (operand must be a STRING).
For example, the following query on the `gl_journal_tx` data table will return transactions with rows that contain the words **abc** , **abcdef**, or **aBcd** in any column.
`{ "$keyword_prefix": "abc" }` | | `$keyword_prefix_not` | Inverted case-insensitive prefix search (operand must be a STRING). | #### Population Operators **Population operators** test whether the specified entry is or is not included within the specified population, identified by its ID. The population in question must be accessible from the analysis, meaning the population must be part of the analysis, engagement, or library that this data table resides in. | Operator | Description | | - | - | | `$population` | Tests that entries are part of the population specified by the provided ID. | | `$not_population` | Tests that entries are not part of the population specified by the provided ID. | The correct usage of `$population` and `$not_population` is as follows, with `643eff00ec992f7ec42ed9f7` being a valid population ID: ```json theme={null} { "$population": "643eff00ec992f7ec42ed9f7" } ``` ```json theme={null} { "$not_population": "643eff00ec992f7ec42ed9f7" } ``` ### Data Formats Because the MindBridge QL is based on JSON, `strings`, `numbers`, and `booleans` are natively included in the language definition, but other values require some conversion. The following table describes the values MindBridge QL accepts in relation to our internal data structure. The contents of the "Column Type" column (below) represent the data types supported internally and how they are mapped to the JSON object structure. | Column Type | Format | | - | - | | `STRING` | Value must be a JSON string. | | `DATE_TIME` | A JSON string in ISO8601 date-time format, such as **2019-08-10T00:50:00Z**. | | `BOOLEAN` | Value must be a JSON boolean (true or false). | | `INT32` | Value must be a JSON number in the range **\[-2^31, 2^31-1]**. | | `INT64` | Value must be a JSON number in the range **\[-2^63, 2^63-1]**. | | `FLOAT32, FLOAT64` | Value must be a JSON number.
FLOAT32 **\[1.2E-38, 3.4E+38]**
FLOAT64 **\[2.2E-308, 1.7E+308]** | | `MONEY_100` | Currently we express currency values as integers, essentially multiplying by 100 to store, and dividing by 100 when displaying the value.
This allows MindBridge to operate with floating point numbers without loss of precision. Value must be a JSON number in the range **\[-2^63,2^63-1]**. No division by 100 is performed on the actual data.
For example, in a `MONEY_100` column, such as credit, the following query on the `gl_journal_lines` data table will find values greater than 1234.
`{ "credit": { "$gt": 1234 } }` | | `PERCENTAGE_FIXED_POINT` | Value must be a JSON number in the range **\[0, 10000]** where 10000 means 100%. | | `ARRAY_STRINGS` | Value must be an array of JSON strings. | | `OBJECT_ID` | A 12-byte database identifier, represented by a 24-character hexadecimal string. Organizations, engagements, analyses, and analysis sources all use **OBJECT\_ID** for their `id` fields.
For example, `6686add55cd5c94147ecebdb` | # MindBridge API Source: https://developer.mindbridge.ai/api-explorer/overview The MindBridge Application Programming Interface (“API”) allows you to control permissions and access to various aspects of your MindBridge tenant, including libraries, organizations, engagements, and analyses. With the API, you can securely push files from your ERP directly into the file manager, import the data into an analysis, and run the analysis — all from outside the MindBridge app. Then, just hop into MindBridge to view the analysis results. # Prerequisites You must be an App Admin to access the API page within the MindBridge application. # How does an API work? An API allows an application to communicate with the MindBridge app through a set of clearly defined commands, enabling secure access to enterprise assets and processes using a REST interface. As displayed in the image below, using an API is similar to placing an order at a restaurant. Think of API commands as ordering off a restaurant menu — the menu defines a list of available "dishes" (like programs or functions), and when you place an order, the kitchen (like the server or database) prepares the food (like the request) in the back, then sends it out to you when it is ready. In brief, APIs define a list of commands. When an ERP uses one of those commands, MindBridge sends back what was requested. Diagram illustrating how an API works. # What is a REST architecture? MindBridge uses a RESTful API architecture, which allows computer systems to exchange information securely over the internet utilizing HTTPS. Requests made via a RESTful API are stateless, and each request contains all of the data necessary to complete the request successfully. # What are the benefits of using an API? * Scalable data ingestion and exporting results using automation * A unified data analysis platform, regardless of industry or organization needs * Secure and controlled access to MindBridge’s data which creates new opportunities for analysis and insights at scale * The automation of complex, repeatable tasks # What is a MindBridge API token? A MindBridge API token is a string of characters that acts as a key to the API, and is implemented as an authentication bearer token. It is utilized by adding the token to the header of each HTTPS request. This token type is a cryptographically secure authentication token that includes the configured permissions allowing API clients to access MindBridge API resources or "endpoints". # What is an endpoint? Endpoints are exposed functions of an application API with functionality provided by HTTPS methods. # What is an HTTPS method? An HTTPS method represents functionality supported by the HTTPS protocol, such as GET, POST, PUT, PATCH, and DELETE. These methods essentially allow you to read, write, or delete libraries, organizations, engagements, analyses, users, and much more. # How long do API tokens last? The token life cycle is configurable by the App Admin for any period of time, up to a maximum of 2 years. # What happens if my API token is compromised? Tokens must be stored in a secure location, and should never be shared. The security of your token is paramount. If a token is compromised, the App Admin should disable and re-issue the token immediately. # How are API tokens generated? An App Admin creates API tokens in the Admin section of the app, where they can apply lifecycle and permissions to each token. Learn how to create a MindBridge API token [here](/api-explorer/create-api-token). # Who can access and use the API? Anyone who has a valid token is able to use the API. App Admins are responsible for managing API tokens, and can grant API access to any users within the engagement. # How do I use the API? To use the API: 1. An API token must be generated by an App Admin within MindBridge. 2. Once you have access to the API token, use the HTTPS protocol to make a request to a documented endpoint in the MindBridge API. Requests can be made using a variety of tools, including most programming languages. In order to utilize a token generated within the MindBridge platform, you must add the following to the header of each HTTPS request: ```text theme={null} Authorization: Bearer {token} ``` # What is the format for communicating with the API? The API utilizes JSON for all request and responses, with the exception of data files, which can be imported in any format supported within the application. # What file formats are accepted through the API? All file formats currently supported by the file manager will be accepted, such as .xlsx, .csv, and more. # What files can I push or pull through the API? ## Inbound All files currently supported by the MindBridge platform can be pushed through the API. Files can be assigned to any of the sources within an analysis, such as the "General Ledger" slot. ## Outbound The API supports paginated analysis results, indexed by transactions, or entries as well. The data available is equivalent to the data table in the MindBridge platform. # Quick Start Source: https://developer.mindbridge.ai/api-explorer/quick-start ## Overview Below are common API workflows and related Knowledge Base articles (requires being logged into MindBridge). * Create a new organization, or find the organization ID of the organization you want to work in [↗](https://support.mindbridge.ai/hc/en-us/articles/9664889181847-Get-an-organization-ID-for-an-existing-organization) * Create a new engagement, or find the engagement ID of the engagement you want to work in [↗](https://support.mindbridge.ai/hc/en-us/articles/9678608725783-Get-an-engagement-ID-for-an-existing-engagement) * Create a new analysis, or find the analysis ID of the analysis you want to work in [↗](https://support.mindbridge.ai/hc/en-us/articles/9680904374295-Get-an-analysis-ID-for-an-existing-analysis) * Load your files into the File manager * Import your files into a target analysis * Run the analysis * Prepare to get the data table results by finding the unique data table ID [↗](https://support.mindbridge.ai/hc/en-us/articles/9683888113431-Get-a-data-table-ID-for-a-specific-analysis) * Get the results from the data table [↗](https://support.mindbridge.ai/hc/en-us/articles/9758842964887-Get-the-data-table-results-for-a-specific-analysis) # Rate limiting Source: https://developer.mindbridge.ai/api-explorer/rate-limiting **Rate limiting** restricts the number of API calls that can be made to certain endpoints over a given period of time, and has been applied to the endpoints indicated below. Once the limit is reached, further calls to any of these endpoints will fail until the rate limit resets. These failures will show the HTTP status: `429 Too Many Requests`, along with a response header: `X-User-Hour-Limit-Remaining`. The value in the response header represents the number of seconds until the rate limit resets. For example, suppose the `POST /users` endpoint has a rate limit of `100` calls per `1 hour`. If more than 100 requests are made within the given hour, any subsequent requests would fail and return the error indicated above. Since rate limiting is applied tenant-wide, all tokens share the same rate limit. ### Rate limits | Name | Reset time remaining header | Limit | Duration | Endpoints | | - | - | - | - | - | | Modify users rate limit | `X-User-Hour-Limit-Remaining` | 100 | 1 hour | - Create user
- Update user
- Resend activation email | ### Platform-level rate limits Additional rate limits are applied at the platform level on a per-IP address basis to protect against potential abuse or client-side software incidents, and are set high enough that customers should not encounter them in regular use. Platform-level rate limits will return the HTTP status `429` with no `X-User-Hour-Limit-Remaining` header, and requests can be retried after approximately 30 seconds. # Security Source: https://developer.mindbridge.ai/api-explorer/security # How is MindBridge securing my data? MindBridge secures your data through: * Access through API tokens (bearer tokens) * Encryption * Rate limiting and prevention of distributed denial-of-service (DDoS) attacks * Leveraging existing security measures to maintain ISO 27001 and SOC 2 Type 2 compliance # What kind of permissions can be applied to each token? Each token has scoped access options for specific areas of MindBridge and permitted actions within those areas. Examples include: * `api.organizations.read` — Grants read access to organizations * `api.organizations.write` — Grants write access to organizations * `api.tasks.write` — Grants write access to tasks * `api.engagements.delete` — Grants delete access to engagements # Can tokens be revoked or re-issued? Tokens can be deleted at any time. While tokens can be renewed, this action does not re-use the existing token, but instead copies the existing settings into a new token. # Can users be deactivated after they have been granted access to the API? App Admins can delete tokens within the application. # How are permissions configured? App Admins can set specific permissions for each token based on user roles, allowing certain aspects of the API to be accessible to some users while restricted for others. **Note:** Tokens must be stored securely. # Account Groupings Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/account-groupings An **account grouping** is a custom financial hierarchy that MindBridge uses to interpret accounts and the relationships between them, and defines how accounts are aggregated and presented in analysis results across the MindBridge platform and reports. When you create an account grouping, you must map account groups to [MindBridge Account Classification (MAC) codes](https://support.mindbridge.ai/hc/en-us/articles/22819163288343-MindBridge-Account-Classification-code-system-MAC-v-2). This mapping enables MindBridge to effectively analyze datasets across any engagements and analyses that use a given account grouping. ## Creating a new account grouping To create a new account grouping, import a completed [MACv2\_AccountGroupingTemplate](https://support.mindbridge.ai/hc/en-us/articles/22819163288343)\* Excel file or a *CCH group trial balance* file as a chunked file. Import the new file using the `/import-from-chunked-file` endpoint. This action will create a new account grouping entry and a complete set of account groups and MAC mappings, as defined in the imported file. \***Note:** The exportable template is located at the bottom of the linked article. Once you have the template, follow the steps linked here to [create a new account grouping](https://support.mindbridge.ai/hc/en-us/articles/360056330754). ## Appending to an existing account grouping To append to an existing account grouping, export the most current version of your MindBridge account grouping, then add new account groups to the bottom of the account grouping, starting from the first empty row. Next, save the file and import it as a chunked file, then import the new file using the `/append-from-chunked-file` endpoint. This action will add the new account groups and mappings to the end of the existing account grouping. **Note:** *CCH group trial balance* files may not be used when appending to an existing account grouping. ## Publishing an account grouping Account groupings must be published before they can be added to a library. In order to be published, errors must be resolved for all account groups within the account grouping, and the lowest-level account categories for each account group must be mapped to a MAC code. To publish an account grouping, set the `publishStatus` field to `PUBLISHED`. Upon publishing, all the account groups within the account grouping are finalized and can no longer be updated, however the account grouping can still be appended to. Appending will change the account grouping’s `publishStatus` to `UNPUBLISHED_CHANGES`. From the `UNPUBLISHED_CHANGES`, the account grouping can be re-published after fixing all account group errors, then updating the `publishStatus` field to `PUBLISHED`. # Account Groups Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/account-groups An **account group** is an individual entry within an account grouping. The lowest-level category for each account group must be mapped to [MindBridge Account Classification (MAC) codes](https://support.mindbridge.ai/hc/en-us/articles/22819163288343-MindBridge-Account-Classification-code-system-MAC-v-2), and optionally, assigned account tags for further classification. Account groups can be updated as needed until the account grouping is published. Once published, existing account groups cannot be updated, but new account groups can be added to the account grouping using the `append` endpoint. # Account Mappings Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/account-mappings *Account mapping* aligns your organization's accounts with MindBridge Account Classification (MAC) codes based on their nature, ensuring that MindBridge can consistently and effectively analyze datasets across the engagement. Before an analysis can be run, all account mappings within the given engagement must be marked as *Verified* or *MAC code*. ## Mapping statuses * **Verified**: Indicates that the account has been mapped to a MAC code or grouping code *automatically*, and/or was previously manually verified. * **Unverified**: Indicates that MindBridge *automatically* mapped the account to a lowest level account grouping code based on the grouping code and/or account description, and should be verified for accuracy before you proceed. * **MAC code**: When using a MindBridge default library, this indicates that the imported general ledger file included a "MAC code" column that accurately reflects the lowest-level MAC code for each account group in the ledger — in this case, MindBridge uses *direct matching* to map the accounts. * **Modified**: Indicates that an account's MAC code was updated when copied between account groupings — this may happen if a *different library* is selected while rolling an analysis forward or duplicating an analysis into a *new engagement*. * **Manual**: Indicates that the account mapping was changed manually by a member of your team. * **Inferred**: When a less granular grouping code or MAC code is provided, this indicates that MindBridge has automatically mapped the account to a Level 3 MAC code based on the provided code and account description, and should be verified for accuracy before you proceed. * **Unmapped**: Indicates that the account has not yet been mapped to a valid MAC code or grouping code. # Admin reports Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/admin-reports **Admin reports** are reports that can be run to summarize user and system activity. Currently, the following reports can be run: * **Activity report** – This report lists activity between the specified dates and filters * **Analysis overview report** – This report lists analyses and the associated risk score results. * **Row usage report** – This report lists analyses completed within your specified date range along with the number of rows in each primary current period data file. # Analyses Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analyses An **analysis** is a logical grouping of financial data that can be run through a series of rules-based, statistical, and machine-learning tests in order to generate analysis results. Once a set of financial data has been configured and imported, an analysis can be run to produce an *Analysis Result* entity, which contains insights into the provided data. Analyses require a number of supporting documents in order to run successfully. After running an analysis, you can view the results and leverage them to support your audit work. ### Analysis Type When creating an analysis, you must identify the **type of analysis** you want to create. To do so, set the `analysisTypeId` field to the corresponding ID for the specific analysis type. The analysis type must be supported by the library used by the engagement. The supported analysis types are listed in the library’s `analysisTypeIds` field. Refer to the Analysis Type endpoint to select an analysis type and review its settings. ### Analysis Periods An **analysis period** is the date range for a given period under analysis. MindBridge supports the analysis of one current period and up to four prior periods. To add analysis periods, add analysis period objects to the appropriate locations in the `analysisPeriods` array. To modify analysis periods, update the `analysisPeriods` array. **Note**: Analysis periods will appear in order, with the most recent appearing in the current period. Periods must not overlap or have date gaps between them. The `interimAsAtDate` must not be set for prior periods. To resize an analysis period, update the `startDate`, `interimAsAtDate` and/or `endDate` to the desired date. See “Interim Time Frames” below for details. To remove an analysis period, remove the target object in the `analysisPeriods` array. The current period (index `0`) may not be removed, nor analysis periods that have associated analysis sources. If you remove the ID from an analysis period, the analysis period will be removed and a new period with the same values will be added, resulting in a new ID being returned. [Learn more about analysis periods](https://support.mindbridge.ai/hc/en-us/articles/360056524494-What-is-an-analysis-period) #### Full Time Frames The **full time frame** allows your team to import a complete dataset. [Learn more](https://support.mindbridge.ai/hc/en-us/articles/19029762802967) To create an analysis with a full time frame, the `interim` and `periodic` fields must be `false` in the body of the Create Analysis request. #### Interim Time Frames The **interim time frame** allows your team to import a portion of a dataset before year-end. [Learn more](https://support.mindbridge.ai/hc/en-us/articles/19030451443223) To create an analysis with an `interim` time frame, the interim field must be `true` in the body of the Create Analysis request. You must also provide an `interimAsAtDate` for the current period, which defines the last day of the interim period. **Note**: The `interim` field cannot be combined with the `periodic` field, which must be `false` if `interim` is `true`. **Note**: The interim time frame must be supported by the analysis type in order to use it. #### Periodic Time Frames The **periodic time frame** allows your team to import data on an ongoing basis, such as monthly or quarterly, over the course of the analysis period. [Learn more](https://support.mindbridge.ai/hc/en-us/articles/19034004957591) To create an analysis with a periodic time frame, the `periodic` field must be `true` in the body of the Create Analysis request. **Note**: The `periodic` field cannot be combined with the `interim` field, which must be `false` if `periodic` is `true`. **Note**: The periodic time frame must be supported by the analysis type in order to use it. Additionally, the periodic time frame and the risk monitoring dashboard are disabled by default in the library's analysis configuration, and must be enabled by an App Admin before they can be accessed. ### Currency The **currency code** indicates the type of currency used in the analysis. A valid currency code must be provided in the `currencyCode` field. **Note**: MindBridge supports the majority of currencies indicated in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Currency code labels used within MindBridge may not match ISO labels exactly, but support for those currencies still exists. **Note**: MindBridge does not support currencies that use more than two decimal places. ### Reporting Periods MindBridge supports custom reporting periods. If your organization has a custom reporting period configuration, you can specify it when creating an analysis by providing the `reportingPeriodConfigurationId` field with the ID of the desired reporting period configuration. If no reporting period configuration ID is provided, it inherits the reporting period set in the engagement. On an update, the existing value will be used if no value is provided. # Analysis Results Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analysis-results An **analysis result** is a logical grouping of financial data that has been run through a series of rules-based, statistical, and machine-learning tests. Each time an analysis is run (or re-run), it will generate a distinct analysis result. Running an analysis multiple times will result in multiple sets of analysis results. ### Task and data table migration for the periodic time frame When an analysis using the *periodic* time frame is re-run, any existing tasks or data tables created on the latest analysis result will be migrated to the new analysis result. Upon completion, the `id` field will be updated to a new value, and the `analysisResultId` field will be updated with the ID of the new analysis result. **Note**: This does not apply to *full* or *interim* time frames, wherein rolling forward, duplicating, or converting interim analyses causes a new analysis being created, with the original analysis results' tasks and data tables remaining in place. # Analysis Source Types Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analysis-source-types An **Analysis Source Type** describes the features applied when importing an analysis source, such as the effective date range, transaction ID selection, etc., as well as relevant MindBridge column definitions. These features determine which steps occur during the analysis source import process. ### Alternative MindBridge field names for non-MAC account groupings When using a non-MAC based account grouping, some MindBridge fields use a different name (for example, `mac_code` becomes `custom_code`). This is identified by the `mindbridgeFieldNameForNonMacGroupings` field, which describes which MindBridge field name to use instead. Additionally, when using a non-MAC based account grouping, some fields may become required. This is indicated by the `requiredForNonMacGroupings` field, which is set for all fields that specify a `mindbridgeFieldNameForNonMacGroupings` value. # Analysis Sources Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analysis-sources An **analysis source** represents a table of data (often from a file) that is required to run an analysis. These objects contain ingestion metadata, including data formats, density and frequency analysis, and much more. The analysis sources are the core object types used during the data import process and provide the data necessary to complete the analysis. ### Analysis source type An **analysis source type** determines which features are available during the analysis source import process, and must be selected when creating an analysis source. Refer to the `Analysis Type` endpoint to determine which analysis source types can be applied to a given analysis. Refer to the `Analysis Source Type` endpoint to determine the features and column mappings for a given analysis source type. #### Additional Analysis Data **Additional data** is available as an analysis source type for all analysis types. When creating an additional data analysis source, the `additionalDataColumnField` property must be set to the additional data field added during the import of other source types. A list of the analysis' additional data columns is available from its `importantColumns` field. ### Async create and update responses Unlike other entities, the analysis source entity may perform long-running background jobs as a result of a `Create` or `Update` call. As a result, calls to `Create` or `Update` an analysis source will return an **async result** entity. Users should poll this entity and await its completion before re-loading the analysis source and making further changes. ### Analysis Source workflow Unlike other entities, importing an analysis source relies on a multi-step workflow process. Which steps are included is determined by which **features** the analysis source type supports. These features include multiple **workflow states**, which determine the current location of the analysis source within the workflow. There are two workflow state types: **step states** and **transition states**. * Step states allow users to configure properties on an analysis source, or the analysis more broadly. Some step states are provided for the MindBridge web app interface and may have little to no meaningful interaction with the API. * Transition states indicate that the analysis source is performing work asynchronously, and will eventually transition to another state. Here is a list of features and their possible workflow states: | Feature | State name | State type | | - | - | - | | Feature independent | STARTED | Transition | | Format detection | DETECTING\_FORMAT | Transition | | | FORMAT\_DETECTED | Step | | | FORMAT\_DETECTION\_COMPLETED | Transition | | Data validation | ANALYZING\_COLUMNS | Transition | | | COLUMNS\_ANALYZED | Step | | Column mapping | DATA\_VALIDATION\_CONFIRMED | Step | | | COLUMN\_MAPPINGS\_CONFIRMED | Transition | | Effective date metrics | ANALYZING\_EFFECTIVE\_DATE\_METRICS | Transition | | | EFFECTIVE\_DATE\_METRICS\_ANALYZED | Step | | | ANALYSIS\_PERIOD\_SELECTED | Transition | | Transaction ID selection | CHECKING\_INTEGRITY | Transition | | | INTEGRITY\_CHECKED | Step | | Parse | PARSING | Transition | | | PARSED | Step | | Review Funds | FUNDS\_REVIEWED | Step | | Confirm Settings | SETTINGS\_CONFIRMED | Transition | | Feature independent | COMPLETED | Step | | | FAILED | Step | ### Transitioning between states To transition between workflow states, set the `targetWorkflowState` property to the name of the desired workflow state. Once set, the workflow will attempt to advance to that state, passing through all states between the current and target state without stopping. If the target state is a transition state, the workflow will continue past it until it reaches the next step state. When creating a new analysis source, if `targetWorkflowState` is not set, the workflow will advance to the first valid step state, then stop. These rules apply to all transitions, with a few exceptions: * If an [ungrouped format](https://support.mindbridge.ai/hc/en-us/articles/10437018464407) is detected within the selected source file, the FORMAT\_DETECTED state will be ignored. Setting `targetWorkflowState` to FORMAT\_DETECTED on a source file containing ungrouped data will result in the workflow continuing to the next step state. * If the final workflow state type is a step state, the workflow will advance to COMPLETED instead of stopping. This is often the case with the PARSED state, as it is the final feature state for many source types. * If an error occurs during a workflow process, the workflow will transition to FAILED. The cause of the failure can often be found in the async result or in the analysis source’s `errors` property. ### Feature properties Certain feature properties may only be read or set on or after specific workflow states. Here is a breakdown of the relationship between workflow states and analysis source properties: #### Format detection If a [grouped data](https://support.mindbridge.ai/hc/en-us/articles/10437018464407) format is detected, the workflow will stop at the FORMAT\_DETECTED state. Then, the `detectedFormat` property will return the name of the detected format. From there, the `applyDegrouper` can be set. If `applyDegrouper` is true then when advancing to the next step, the relevant formatter will be used to convert the file into a readable format. If not, the file will be used as is. `applyDegrouper` can be set immediately upon creation of the analysis source. If this is done and grouped data is detected within the workflow, instead of stopping on FORMAT\_DETECTED it will implicitly apply the formatter and continue to the next workflow state. If the formatter is used in either scenario, the `degrouperApplied` property will be set to `true`. The `presetHeaderRowIndex` field can be set to manually specify the header row’s position in the imported file, bypassing automatic header detection. The field is zero-based, so the first row in the file is considered row 0. #### Data validation Upon reaching the COLUMNS\_ANALYZED state, the `fileInfo` property is populated with information, including metadata for the individual columns (which is available as part of the `columnData` property) and for the file as a whole (available under the `metadata` property). Metrics contain a `state` property, which may appear as `PASS`, `WARN`, or `FAIL`. These serve as status indicators and may warn of problems with the file’s data. #### Column mapping Upon reaching the DATA\_VALIDATION\_CONFIRMED state, the `proposedVirtualColumns`, `proposedColumnMappings`, and `proposedAmbiguousColumnResolutions` properties are applied, and the `virtualColumns`, `columnMappings`, and `ambiguousColumnResolutions` properties are updated accordingly. More information on the proposed fields is available in the **Full source import automation** section. If no value is present for `proposedColumnMappings`, then a set of recommended column mappings will be applied to the file. The API handles column mapping by assigning a column from the file to a MindBridge field with a compatible data type. To do this, an entry in the `columnMappings` array must contain both the `position` of the column from the source file and the target `mindbridgeField` to assign it to. #### Virtual columns [Virtual columns](https://support.mindbridge.ai/hc/en-us/articles/10442701235223) can be added, modified, and removed by changing the `virtualColumns` property. Once created, virtual columns have a `position` property that can be used in column mapping; the metrics in `fileInfo` will be updated accordingly. #### Ambiguous column resolution While MindBridge can detect usable date formats, including different formats that appear within a single column, in some cases the format of date and currency fields cannot be determined from the dataset provided. For example, the date format `1/2/2022` could either be January 2nd, 2022, or February 1st, 2022, depending on which date format is being used. When ambiguous columns are detected, an entry in the `ambiguousColumnResolutions` property will be created with a list of all the possible formats in its `ambiguousFormats` property. To resolve this issue, the correct format from the list of `ambiguousFormats` should be set in the `selectedFormat` property. #### Additional data Unmapped columns may be added as additional data columns. To do so, a special mapping must be created with the `mindbridgeField` left blank, and a value set for `additionalColumnName`. Once this source has completed the import process, a new source with the same name set for `additionalDataColumnField` and the source type ID corresponding to the Additional Data Source Type can be created. #### Effective date metrics This step confirms that the file’s entries fall within the current analysis period. Once this state has been reached, the `analysis-sources/{analysisSourceId}/effective-date-metrics` endpoint can be used to get a set of metrics regarding the number of entries within the source’s analysis period. A `period` value can be used to set the resolution of the histogram to days, weeks, or months. #### Transaction ID selection Transitioning into the [transaction ID](https://support.mindbridge.ai/hc/en-us/articles/8740577590295) selection feature will generate a preview of the selected transaction by `proposedTransactionIdSelection` and set the `transactionIdSelection` property to this value. If no value is set, a set of potential transaction ID selections will be generated and what is determined to be the best selection, according to MindBridge's internal tooling, will be set to the `transactionIdSelection` property. Details about these **transaction ID previews** can be viewed via the transaction ID preview endpoints. When on the INTEGRITY\_CHECKED state, changing the `transactionIdSelection` will either select an existing preview with the same properties as the currently selected transaction ID, or, if it doesn’t exist, will generate a new preview for the selection, and select it. #### Review funds and confirm settings These features have no direct interaction with the API and are only relevant with respect to the web application. ### Full source import automation When creating a new analysis source it is possible to perform the entire import process by setting the `targetWorkflowState` property to `COMPLETED`. As a result of performing all workflow steps at once, some features require input to be provided immediately, specifically the column mapping and transaction ID selection features. To provide these values, separate `proposed` fields can be set in order to provide these values instead of relying on the default column mapping and transaction ID selection behavior. #### Column mapping The `proposedVirtualColumns`, `proposedColumnMappings`, and `proposedAmbiguousColumnResolutions` properties provide the ability to pre-define their respective properties ahead of running validation. These proposed versions of the properties have some key differences from their applied counterparts: * As validation has not been run and the column positions have not been determined, the `position` property for virtual columns isn’t available. As an alternative to the `proposedColumnMappings` property, a `virtualColumnIndex` property is available and should be used to reference a specific virtual column definition in the `proposedVirtualColumns` array. * `proposedAmbiguousColumnResolutions` are not able to determine the ambiguous formats ahead of validating the file, so the `ambiguousFormats` property is not available. Additionally, the `position` property can only refer to a physical column, and not a virtual one. #### Transaction ID selection The `proposedTransactionIdSelection` property can be defined immediately upon creating the analysis source. If it is set while entering the transaction ID selection feature then a transaction ID preview will only be generated for that selection, and `transactionIdSelection` property will be updated accordingly. # Analysis Type Configuration Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analysis-type-configuration An analysis type configuration is the configuration of analysis properties for a given analysis type. Libraries, engagements and analyses all have analysis type configurations as child entities for each of their supported analysis types. When an engagement is created, it will copy the analysis type configuration from the related library, and again when an analysis is created it will copy the analysis type configuration from its related engagement in turn. Analysis type configuration allows configuration of settings related to control points, including grouping and weighting of control points, as well as the selection of related risk ranges. # Analysis Types Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/analysis-types **Analysis types** describe the features of each analysis, such as specific account mappings or whether the analysis supports fund accounts, as well as the source configurations used for a given analysis type. [Learn more about the types of analyses available within MindBridge](https://support.mindbridge.ai/hc/en-us/articles/360058198913-Analysis-types-available-in-MindBridge) # API Tokens Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/api-tokens **API tokens** are used to authenticate requests made to the MindBridge API. During creation, each token is assigned permissions that control the actions it can perform. API tokens are valid until their expiry date, after which they can no longer be used. A token may be active for a maximum of 2 years from the date of creation. Additionally, API tokens can be configured to limit access to specific IP addresses or CIDR blocks by setting the `allowedAddresses` property to a valid IPv4 or IPv6 address, or CIDR range. ## API Token Users Once an API token is created, an **API Token User** is automatically created and assigned to the API token. This non-human user account represents the API token, and any action that the API takes will be attributed to that user. Because each API Token User is linked to a unique API token, these accounts cannot be deleted or disabled, except by deleting the associated API token itself. # Async Results Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/async-results **Async results** can be used to track the status of asynchronous background jobs (such as data ingestion) for which results may not be immediately available. Users can poll these records to view the status of their requests. Once the requests have been completed, users can call the relevant entity’s `Read` endpoint to view the results of the job. ### Permissions The **permissions** needed to access this collection are controlled by the target data you are attempting to access. # Chunked Files Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/chunked-files Importing **chunked files** allows you to bypass the 8 GiB import limit by splitting a large file into smaller files (“chunks”). Each chunk can be individually retried in case of a network failure, but the entire import process must be completed within 7 days. ### How it works: * Create a chunked file. * Add chunked file parts. * Create a file manager file from a chunked file. # Connection Tables Results Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/connection-tables-results **Connection Tables Results** represent the outcome of running a Connection's "Get Tables" operation. The Connection Tables Result is stored as a record containing the total number of tables found. The individual tables discovered are stored as separate Connection Table records linked back to this Connection Tables Result. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Connection Test Results Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/connection-test-results **Connection Test Results** represent the outcome of running a Connection's "Test Connection" operation. The Connection Test Result is stored as a record containing a message indicating whether the connection was successful or describing the failure. #### Cleanup task A cleanup task is regularly run that will delete Connection Test Results that are older than 7 days. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Connections Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/connections **Connections** represent external data sources configured in MindBridge. Connections allow you to connect to external systems, test connectivity, discover available tables, and retrieve data for use in MindBridge. The following types of connections are currently available: * `DATABRICKS` - A connection to a Databricks workspace. This requires a Databricks Authorization entity to be associated with this connection to provide configuration and authorization parameters. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Data Catalog Entries Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-catalog-entries **Data catalog entries** are curated remote and local data sets accessible in MindBridge. These data sets can be annotated on the table and column level and can be queried to produce a data table. Currently, the following data sources can be used to create data catalog entries: **MindBridge data tables** A data catalog entry can reference an existing MindBridge data table. These catalog entries must have their `source` field set to `DATA_TABLE`, and a valid `dataTableId` set to a data table ID. Data catalog entries can use all data tables accessible by the API as sources. **Connection tables** Tables provided by the connections feature can be used in data catalog entries. These catalog entries must have their `source` field set to `CONNECTION`, and both connectionId and tableId values set. Data catalog entries are not actively validated for alignment with their underlying source and may need to be manually validated and corrected if the remote source’s schema is not compatible with the schema provided by the data catalog entry. The data catalog does not need to include all columns provided by the remote source, but the name and columnType fields of the columns must align with the underlying source name and type respectively. Columns that are not nullable in the source may not be nullable in the data catalog. Failure to properly align the column schemas may result in errors when attempting to read data from the data catalog entry. Data types are not implicitly converted, so the exact same data types must be present in the data source and the data catalog entry. **Data Flows** Using a data flow as a source allows transformations to be applied to an existing data catalog entry. Catalog entries that are created from a data flow must have their `source` field set to `DATA_FLOW`, and a valid `dataFlowId` set to a data flow ID. Data flows and catalogs cannot be connected in such a way that would cause a circular dependency. Attempting to do so will result in an error during validation or when attempting to import data. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Data Connection Tables Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-connection-tables **Connection Tables** represent individual tables discovered from an external connection. When a Connection's "Get Tables" operation is performed, the results are stored as Connection Table records. Each record contains the table's identifier, display name, and schema (column definitions), and is linked back to both the Connection and the Connection Tables Result that produced it. If the "Get Tables" operation is run multiple times on the same Connection, tables are added, removed, or updated based on their `tableId`, rather than creating duplicate entries. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Data Flows Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-flows **Data Flows** are used to transform the data provided by a data catalog entry. The data catalog from which to pull data is defined by the `inputDataCatalogEntryId` parameter and is then transformed in order by the data flow operations defined by the `operations` parameter. Data flows themselves don’t have an explicitly defined schema but can be queried for data or used as a source for a data catalog, similar to data tables or connections. The schema of data produced is determined by the transformations applied. The following data flow operations are available: **Remap** - `"type": "REMAP"` Changes the column names identified by the list of source/destination pairs. This can be used to rename existing columns. The same column can be remapped into multiple output columns, effectively duplicating it. Columns that are not defined in the operation will not be included in the output. To include a column without renaming it, you must set both the source and destination to the original column name. Multiple sources cannot be mapped to the same destination. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Data Source Import Tasks Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-source-import-tasks **Data source import tasks** are records of in-progress or past data source import jobs where data is being imported into MindBridge from a local or remote data source. **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Data Tables Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-tables After running the analysis, the **data table** provides results details about the imported financial data for the current period. ### Logical names and types Data tables types can be identified by either their `logicalName` or `type` field, depending on the data table, and can be queried accordingly using the following fields: | Table | Field | Value | | - | - | - | | General Ledger Entries | `logicalName` | `gl_journal_lines` | | General Ledger Transactions | `logicalName` | `gl_journal_tx` | | Monetary Flows | `type` | `flows_compact` | | Accounts Payable Entries | `logicalName` | `ap_detail_entries` | | Accounts Receivable Entries | `logicalName` | `ar_detail_entries` | | Accounts Payable: End of Period Outstanding Payable | `logicalName` | `ap_detail_union_open_payables` | | Accounts Receivable: End of Period Outstanding Receivables | `logicalName` | `ar_detail_union_open_receivables` | | Configured Analysis Entries | `logicalName` | `output_entries_virtual` | ### Table API stability The API includes data tables with stable schema as well as tables with unstable schema, where the schema might change in the future or may even be removed. By default, the data table query API returns tables with stable schema only. To include tables with unstable schema in the results, add `include-unstable-schemas=true` to your query string. For example, `https://.../api/v1/data-tables/query?page=0&size=20&include-unstable-schemas=true`. # Data Transformation Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/data-transformation The **data transformation** endpoint is a collection of data manipulation techniques that can be performed on file manager files. These transformations can be applied to one or more files, and typically generate new files based on specified input configurations. # Databricks Authorization Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/databricks-authorization **Databricks Authorizations** store the credentials and configuration required to authenticate with a Databricks instance. Each authorization is associated with a Connection and contains the host, HTTP path, and authentication details (either a personal access token or OAuth 2.0 machine-to-machine credentials). Each Connection can have at most one Databricks Authorization — creating a new authorization for a Connection that already has one will fail. The `authType` field determines which credentials are required: * **PAT** (Personal Access Token): Uses `host`, `httpPath`, and `accessToken`. The `port` is optional (typically 443). * **OAUTH\_M2M** (OAuth 2.0 Machine-to-Machine): Uses `host`, `httpPath`, `clientId`, and `clientSecret`. The `port` is optional (typically 443). **Notice**: This endpoint is part of a feature under active development. It may be subject to change in future releases. For more information, please contact your MindBridge account representative. # Engagement Account Groupings Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/engagement-account-groupings An **engagement account grouping** is an engagement-level copy of an account grouping that is generated upon creation of a new engagement. Subsequent changes made to the original account grouping and/or its account groups will not be copied into the engagement account grouping, and vice versa. # Engagement Account Groups Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/engagement-account-groups An **engagement account group** is an individual entry within an engagement account grouping. # Engagements Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/engagements An **engagement** represents a service or activity performed for one of your clients. When you create an engagement within an organization, it will always be associated with that organization. Engagements house the analyses you run within MindBridge, like the general ledger analysis. Typically engagements represent an annual audit, so using MindBridge over the course of several years will result in multiple engagements within an organization, each corresponding to a fiscal year. The reportingPeriodConfigurationId is an optional field. If provided, it will use the custom reporting period configuration specified by the ID. If not provided, it will default to the default reporting period configuration. # File Info Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/file-info *File Info* is an entity used to describe metadata for a file within the MindBridge application. Every file has an associated File Info record. If the system detects tabular data in the file, the File Info is automatically upgraded to a Tabular File Info, which includes additional metadata describing the table and columns. The type of file info is determined by the `type` field. If the value is `FILE_INFO`, the record is a file info. If the value is `TABULAR_FILE_INFO`, the record is a tabular file info. # File Manager Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/file-manager The **file manager** is a secure, centralized holding area designed to store files related to an engagement. It supports a folder-based hierarchy, allowing data to be utilized for various purposes. Files stored in the file manager can be imported into appropriate analysis sources\*. \***Note:** The file manager can hold any number of files, but the analysis source types available within an engagement are controlled by the selected library and the analysis types it supports. # File Results Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/file-results **File results** are the results of asynchronous processes that produce files. They can be exported once the async result reports that the task is complete. File results are restricted to the API token that started the export process. File results created by another user or API token cannot be accessed. # GDPdU Unpack Jobs Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/gdpdu-unpack-jobs GDPdU Unpack Jobs record asynchronous archive unpack operations and the File Manager files and directories they create. # JSON Tables Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/json-tables A JSON Table is a collection of tabular data structured into one or more pages of JSON arrays, imported into the MindBridge platform. Each array consists of objects, where for each object, the keys represent column headers and their associated values represent the data for that column. Data must be uploaded sequentially, one page at a time, as concurrent page uploads are not supported. Once all data has been appended to the JSON Table, a file manager file can be created using the file manager's `Import From JSON Table` endpoint, which merges all the parts into a concatenated CSV file. The headers in the resulting file are based on those specified in the JSON Table, and the order of the headers will correspond to the sequence in which each unique header appears in the source data. For example, given the following two pages of JSON Table data: ```json theme={null} [ { "Account": "First Account", "Amount": "10.11$", "Date": "2020-01-01" }, { "Account": "Second Account", "Amount": "89.99$", "Date": "2020-01-02" } ] ``` ```json theme={null} [ { "Account": "Third Account", "Amount": "33.31$", "Date": "2020-01-03" }, { "Account": "Fourth Account", "Amount": "10.11$", "Memo": "My Memo" } ] ``` The resulting CSV file would be the following: ``` "Account","Amount","Date","Memo" "First Account","10.11$","2020-01-01","" "Second Account","89.99$","2020-01-02","" "Third Account","33.31$","2020-01-03","" "Fourth Account","10.11$","","My Memo" ``` ### JSON Table entities cleanup JSON Table entities that are more than **7 days** old will be deleted. To avoid data loss, ensure that all JSON Table entries are imported as file manager files once all the data has been imported. # Libraries Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/libraries **Libraries** allow teams to standardize their engagements firm-wide by setting the parameters for each type of analysis available in MindBridge, including account groupings, ratios, filters, and risk scores. New libraries must be created based on an existing library (i.e., a “base library”). When a base library is selected, its point-in-time settings and permissions are copied to the new library. The following system libraries can be selected as base libraries: * MindBridge for-profit * MindBridge not-for-profit * MindBridge not-for-profit with funds * MindBridge review # Organizations Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/organizations **Organizations** represent each business/client/company/entity that you analyze with MindBridge. Organizations house all of your client’s engagements (audit/analysis), account mappings, and any other data imported into MindBridge for that client. # Populations Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/populations **Populations** allow users to group entries within an analysis to support more efficient sampling. Unique populations can be defined within libraries, engagements, and analyses, and can be used to surface or exclude groups of entries from the analysis results. Some fields (below) within population entities may only be defined for populations depending on their parent entity. Library populations: * `libraryId` Engagement populations: * `engagementId` * `derivedFromLibrary` * `disabledForAnalysisIds` * `promotedFromAnalysisId` Analysis populations: * `analysisId` * `derivedFromEngagement` Each population inherits permissions from its parent entity type. In order to access library, engagement, and analysis populations, you will need to be able to access libraries, engagements, and analyses respectively. If the API token does not provide sufficient access, those populations will be excluded from `GET` and /`query` results. ### Population conditions Populations use the same condition format as saved filters. Please refer to the saved filters documentation for a description on how the condition formats work. Population conditions have additional restrictions in addition to those applied to saved filters: * The following fields cannot be used as part of a population condition: `populations`, `account_tags_decreasing`, `account_tags_increasing`, `status` and `risk_range`. * Populations can only be applied to general ledger analysis types. Unlike filters, populations are validated on creation and when updated. A create or update to a population condition that doesn't align with the analysis' data table definition will fail. Additionally, unlike filters, populations can only be applied to general ledger entries, not transactions. Similar to filters, populations include the fields `legacyFilterFormat`, `displayCurrencyCode` and `displayLocale`, which function in the same way as they do for saved filters. # Reporting Period Configuration Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/reporting-period-configuration **Reporting period configurations** allow users to define specific reporting periods for analyses. Creating a reporting period configuration requires both monthly and weekly reporting periods to refer to the same date ranges. The monthly reporting period entries should include the period number, quarter number, the year, start date, and end date for each period. Similarly, the weekly reporting period entries should contain the week number, year, start date, and end date. # Risk Ranges Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/risk-ranges Risk ranges are customized scoring parameters for grouping risk scores into low, medium, and high risk range bounds. Each risk range bound has a low threshold and a high threshold. These values represent percentage values with two-decimal precision. The thresholds are `PERCENTAGE_FIXED_POINT` values, which are percentages with two decimal places, represented as numbers from 0 to 10,000. For more details on this data format, refer to the Data Formats section of the API reference. You are not required to utilize all risk range bounds, however you must define at least two ranges. The values must be continuous with no gaps, and no overlapping values. If a low risk range has a high threshold of 15% (represented as `1500`), the low threshold of the next risk range must start at 15.01% ( represented as `1501`). Risk ranges are designed to be used in conjunction with analysis type configurations. Risk ranges can only be added to libraries, and are copied onto new engagements that select the library when created. Once copied to the engagement, the risk range can no longer be updated. # Risk Segmentation Configs Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/risk-segmentation-configs **Risk segmentation configurations** are saved views for the Risk Segmentation dashboard on an analysis. Each config describes how results should be broken down (the **segments**), which summary **columns** appear in the table, and optional dashboard **filters**. Configs correspond to the segment picker in the web application. This API manages those saved configurations only. It does **not** return dashboard table data or support drilling into entries. (The web app loads table rows through separate private endpoints.) Each config belongs to one analysis. `analysisId` is the analysis **run** id (the same id returned by `/v1/analyses` for the run, not the analysis context id). Names must be unique within an analysis. ### Typical workflow 1. **Create** a config with `analysisId`, a unique `name`, ordered `segments`, and ordered `columns`. 2. **Query** configs for an analysis (for example `{ "$eq": ["analysisId", ""] }`). 3. **Read** a config by id when you need the full definition. 4. **Delete** configs you no longer need. There is no update operation on the public API. To change a config, delete it and create a new one. ### Segments `segments` is an ordered list. Order defines the hierarchy shown in the dashboard table (outer segments first, inner segments nested beneath them). Each value must be a valid SQL identifier. **`risk_score` is required** in `segments`. Create requests without it are rejected. #### Built-in segment keys (general ledger and similar analyses) | Segment | Meaning | | - | - | | `risk_group` | Risk assertion category (for example asset vs profit-and-loss assertion scores). | | `risk_score` | Individual risk score (ensemble). **Required.** | | `account_l1` … `account_l5` | Account grouping hierarchy levels. Use only levels that exist for the analysis. | | `population_` | Group by a population tag code (prefix is literal `population_`). | | `category_` | Group by a population category code (prefix is literal `category_`). | The web application builds population segment ids from enabled populations on the analysis. #### Custom analysis segments For custom (flex) analyses, additional segment fields may be used when they name **categorical** columns on the analysis entry data table. Those names must be valid SQL identifiers and must exist on the table. The analysis designer uses the same rules when defining risk segmentation there. ### Columns `columns` is an ordered list of metric fields displayed in the dashboard table for each segment row. Values must match the snake\_case ids below (these are the same ids the web application sends as `columns`). #### Count and value summaries | Column | Meaning | | - | - | | `total_count` | Entry count in the segment. | | `total_value` | Total monetary value. | | `total_value_dr` | Total debit value. | | `total_value_cr` | Total credit value. | | `net_activity` | Net activity value. | | `risk_avg` | Average risk score in the segment. | #### High / medium / low counts and values | Column | Meaning | | - | - | | `high_count`, `medium_count`, `low_count` | Entry counts at each risk level. | | `high_value`, `medium_value`, `low_value` | Monetary totals at each risk level. | | `high_value_dr`, `high_value_cr`, … | Debit/credit splits of H/M/L value columns (same pattern as above). | #### High / medium / low percentages | Column | Meaning | | - | - | | `percent_high_risk`, `percent_med_risk`, `percent_low_risk` | Percent of entries at each risk level. | | `percent_high_risk_dr`, `percent_high_risk_cr`, … | Debit/credit splits of the percentage columns (same pattern). | Debit/credit column variants apply to general ledger analyses that expose separate debit and credit totals. Omit them when not relevant to the analysis type. Do **not** put segment keys (such as `risk_group` or `account_l1`) in `columns`; those belong in `segments`. ### Optional filters These fields mirror the **Risk group** and **Risk score** filters on the dashboard facet bar. They restrict which scores and categories are in scope when the config is opened. They do not add extra grouping levels. | Field | Meaning | | - | - | | `riskScoreIds` | Risk score ids (ensemble object ids) to include. When omitted or empty, all enabled risk scores for the analysis are in scope. When `risk_score` is not a segment, this still limits which scores contribute to aggregated columns. | | `riskGroups` | Risk group category names to include (for example `GENERAL`, `ASSETS`, `PROFIT_LOSS`, or a custom risk score category name). When omitted or empty, all groups are in scope. | `riskGroups` values are **category labels**, not risk range ids and not entries from `/v1/risk-ranges`. ### Other fields | Field | Meaning | | - | - | | `displayCellVisuals` | When `true`, the dashboard shows in-cell sparkline visuals for numeric columns. Defaults to `false`. Maps to internal `displayTableSparklines`. | | `enabled` | Whether the config is active. Defaults to `true`. Disabled configs remain stored but are not selected by default in the web application. | | `analysisTypeId` | Set automatically on create from the analysis. Returned on read and query; do not send on create. | ### Example create request ```json theme={null} { "analysisId": "123456789012345678901234", "name": "Risk group and score", "segments": ["risk_group", "risk_score"], "columns": ["total_count", "total_value", "risk_avg"], "displayCellVisuals": false, "enabled": true, "riskScoreIds": ["abcdefabcdefabcdefabcd"], "riskGroups": ["GENERAL", "PROFIT_LOSS"] } ``` ### Validation * `analysisId` must reference an existing analysis run. * `name` must be unique among configs for that analysis. * `segments` must include `risk_score`. * Segment and column names must be valid SQL identifiers. * Invalid segment or column combinations for the analysis type may be rejected at create time. ### Query See the query operation description for filterable fields. # Saved Filters Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/saved-filters **Saved Filters** are used to filter data tables in order to easily and repeatedly extract insights on large sets of data. The saved filters endpoint allows for easy creation and management of saved filters, and validation of the applicability of filters across different data tables and even across engagements and organizations. Saved filters contain **conditions**, which are definitions on how the filter applies constraints on the underlying data table. These conditions contain a field, type and various parameters depending on the condition type. The field can either specify a column in the data table (with some constraints), or a special case field name, which provides the ability to filter the data table on features of the dataset that are not represented by a specific column. The condition type determines how the data will be filtered. Which types can be applied depends on the data table's column type and other properties. For special case filters the type parameters depend on the underlying data table and analysis features. See the *Condition Types* section for more details. Saved filters can be used to filter general ledger, accounts payable, and accounts receivable analyses. They cannot be used as part of custom analysis types. ### Validation Saved filters are different from other entities in the MindBridge API in that the filter conditions are not immediately validated upon creation. This is because they may or may not be applicable to different target data tables based on the analysis features and the column present in the data table, and their types. To validate whether a given filter is compatible on a target data table a `/validate` endpoint is provided, which will return a list of errors and warnings explaining incompatibilities between the provided filter and the target data table. ### Display fields Saved Filter conditions include various fields that are used in generating a description of the filter for each condition. This description is visible in the web application and presents the filter in plain English. In the web application, filters can only be created in either a library or analysis context, and have immediate context with which to base the display fields on. The API doesn't require this context, and can therefore create filters in contexts the web application can't, such as on an organization or engagement without any analyses. In order to generate a sensible filter description for use in the web application, users of the API can optionally provide these values, and verify if they align with a target data table using the `/validate` endpoint. ### Filter types Filters can be of one of four types: `LIBRARY`, `ORGANIZATION`, `ENGAGEMENT` and `PRIVATE` Library, organization, and engagement types determine which parent entity type the filter is stored under, and in some cases restrict which fields can be used on those filters. Private filters function like organization filters, but they are only accessible by the user that created them. This also applies to the API users, who can only see private filters created by that same token user. The API cannot be used to access private filter created by other users, including other token users. ### Filter data type Filter data type is used to determine what kind of data the filter intends to target, and can be set to the values: `TRANSACTION_FILE`, `ENTRIES_FILE` or `LIBRARY_ADMIN_TABLE`. The `TRANSACTION_FILE` value corresponds to the transactions data table in a general ledger analysis. The `ENTRIES_FILE` corresponds to a general ledger, accounts payable and accounts receivable entries tables. ### Disallowed fields The following fields cannot be used as conditions: * `account`, if the analysis is a general ledger analysis * `accounts` or `mac_hierarchy`, if the data table column type is `ARRAY_STRINGS` * `txid`, `rowid` or `matched_entry_id`, if the data table column type is `INT64` * `total_amt`, if the data table column type is `MONEY_100` * `invoice_paid_zero_date`, if the data table column type is `DATE_TIME` * Any data table column whose field name starts with "`cp_score_`" * Any data table column whose field name starts with "`risk`", and has data table column type `PERCENTAGE_FIXED_POINT` * Any column that does not have a data table column type of `KEYWORD_SEARCH` or `LEGACY_ACCOUNT_TAG_EFFECTS`, and without one of `equalitySearch`, `rangeSearch` and `containsSearch` being `true` ### Condition types Condition's types are determined by their `type` field. Some condition types also contain subtypes, which further determine what fields are required to configure them. Broadly there are 2 types of conditions: Group type conditions, and value conditions. Group conditions don't require a field or other properties, and instead contain a sub-list of conditions that are applied against the data table entries. Value conditions filter a specific field and cover all other condition types other than `GROUP`. In addition to `field` they have the following properties: * `fieldLabel` - An optional display name for the field which is used in the full condition description. * `negated` - When `true` the condition will instead exclude any entry that matches the condition from the result. * `fullConditionDescription` - A description of the filter in plain English, using the provided display values such as `fieldLabel` and others. #### `GROUP` type conditions Group conditions, also known as rules, don't require a field, and contain both an operator and a list of conditions. The operation can be either `AND` or `OR`, and the condition will match records that meet all or any of the conditions, depending on the operator. Group conditions can be nested, and the value of the `condition` field on a saved filter must be a group condition, though it can be either type. ```json theme={null} { "type": "GROUP", "operator": "AND", "conditions": [ ... ] } ``` #### `STRING` type conditions String type conditions compare a field against a specific string value. This condition can only be applied to the following special case fields: | **Field** | **Name** | **Allowed Values** | **Notes** | | - | - | - | - | | `accountScoping` | Account Scoping | SIGNIFICANT, INSIGNIFICANT, UNSCOPED | Only allowed on general ledger analyses. | | `riskGroup` | Risk Group | Not `GENERAL` or `MindBridge Score`

ASSETS, LIABILITIES\_EQUITY, PROFIT\_LOSS, or any custom account group by `category` name. | Only allowed on general ledger analyses. | #### `STRING_ARRAY` type conditions String array conditions compare the field against a set of string values. It can be applied to any data table column with the following properties: * Data table column type is `STRING` and `caseInsensitivePrefixSearch` is `true`. * Data table column type is `KEYWORD_SEARCH`. #### `CONTROL_POINT` type conditions Control point conditions match a set of selected control points within their respective high, medium and low risk scores. The control point type can only be used with the field `cp_failed` and when the data table column type is `BOOLEAN_FLAGS`. The `riskLevel` property can be set to `HIGH_RISK`, `MEDIUM_RISK` or `LOW_RISK`. The `controlPoints` contains a list of control point selection models, with the following properties: * `id` - The unique ID of the control point prefixed with `custom_`, in the case of custom control points, or the symbolic name, in the case of MindBridge control points. * `name` - The display name of the control point. Optional. * `symbolicName` - The symbolic name of the control point. In the case of custom control points it must be the symbolic name of the underlying MindBridge control point. * `isRulesBased` - Must be `true` if the target control point is rules based. Rules based control points can only have high and low risk values, and therefore cannot be selected with a `riskLevel` of `MEDIUM_RISK`. Here is an example of both a MindBridge and a custom control point: ```json theme={null} { "type": "CONTROL_POINT", "field": "cp_failed", "fieldLabel": "Control point", "negated": false, "riskLevel": "HIGH_RISK", "controlPoints": [ { "id": "custom_682fab332f732c4d0b8d1ced", "name": "Expert Rules - Example Custom Control Point", "symbolicName": "journal_entry_flat_expert_flow_v2", "rulesBased": false }, { "id": "journal_entry_two_digit_benford_v2", "name": "2 Digit Benford", "symbolicName": "journal_entry_two_digit_benford_v2", "rulesBased": false } ] } ``` #### `ACCOUNT_NODE_ARRAY` type conditions Account node array type conditions match an entry if it's within an account group or specific account code within varying contexts. This condition type can only be used for general ledger analyses. The following fields use the account node array type: | **Field** | **Name** | **Notes** | | - | - | - | | `account_hierarchy_codes` | Account | Matches if the entry is associated with an account within the selection of accounts. | | `increasingCredits` | Increasing Credits | Matches if the entry is associated with an account within the selection of accounts and the credit value within those accounts are increasing. | | `increasingDebits` | Increasing Debits | Matches if the entry is associated with an account within the selection of accounts and the debit value within those accounts are increasing. | Both `increasingCredits` and `increasingDebits` are special case fields and can be used even if they are not present as data table columns. When using an `ACCOUNT_NODE_ARRAY` condition a list of account selections must be provided with the following properties: * `name` - The display name of the account. Optional. * `code` - The account group or account ID of the account. * `useAccountId` - If `true` the condition should match the account id from the account mapping instead of the account group ID for this selection. Here is an example of a condition that matches both an account group and a mapped account: ```json theme={null} { "type": "ACCOUNT_NODE_ARRAY", "field": "increasingCredits", "fieldLabel": "Increasing credits", "negated": false, "accountSelections": [ { "name": "Assets", "code": "1000", "useAccountId": false }, { "name": "Accounts Payable", "code": "21011", "useAccountId": true } ] } ``` #### `TYPEAHEAD_ENTRY` type condition The typeahead entry type condition can be used to match one or more string values within a known set of allowed values. They are used both to filter columns that have been mapped to certain MindBridge field and additional columns marked as filterable. There are also additional special case field that can be used for various purposes. | **Field** | **Name** | **Notes** | | - | - | - | | `status` | Status | Matches entries which contain corresponding tasks with the selected statuses. | | `memo` | Suspicious keyword | Allowed values are from the Suspicious keyword control point. | | `entriesFundRestriction` | Fund restriction | Allowed values are `restricted`, `unrestricted` and `none` | | `transactionsFundRestriction` | Fund restriction | Allowed values are `restricted`, `unrestricted`, `both` and `none` | | `account_tags_increasing` | Increasing account tags | Matches entries whose accounts using the provided account tags have increased in value. | | `account_tags_decreasing` | Decreasing account tags | Matches entries whose accounts using the provided account tags have decreased in value. | In addition to the above field, any data table column with the type `STRING` or `ARRAY_STRINGS` and an ID set for `typeaheadDataTableId` can be used in a typeahead entry condition. The allowed values for typeahead based fields are any of the values present in the column. Typeahead column values are not currently validated, so no warnings will be produced if a value that is not present in the column is used as an entry. A value selection for a typeahead entry has three properties: `lookupId`, which is the value being selected, `displayName`, which is the display name of the underlying value, and `hideLookupId`, which hides the lookup ID when displaying the full display name. Here is an example of a typeahead entry condition: ```json theme={null} { "type": "TYPEAHEAD_ENTRY", "field": "entriesFundRestriction", "fieldLabel": "Fund restriction", "negated": false, "values": [ { "lookupId": "none", "displayName": "No fund information", "hideLookupId": true }, { "lookupId": "restricted", "displayName": "Restricted funds", "hideLookupId": true } ] } ``` #### `POPULATIONS` type condition The populations type condition matches any entries that are within the provided populations. Population type conditions can only be used in general ledger analyses, and can only be used in saved filters at the analysis level. Populations type conditions must use the special case field `population`. Population type conditions can only be applied to general ledger analyses. To include a population in the condition it simply needs to be added to the `populationIds` field. In addition to IDs, population category names can be present in the population IDs list for display purposes. Here is an example of a populations filter: ```json theme={null} { "type": "POPULATIONS", "field": "population", "fieldLabel": "Population", "negated": false, "populationIds": [ "Custom Category", "67d06587edfa507f5e80c7c2" ] } ``` #### `RISK_SCORE` type condition A risk score condition matches entries whose risk score falls within the constraints configured in the condition. The specific risk score being tested is selected by setting the `riskScoreId` field to the field of the target risk score, as found in the data table column metadata. Risk scores are used on the special case fields `riskScoresHml` or `riskScoresPercentage`, depending on the library configuration for the analysis. Additionally, the `riskScoreType` must be set to `HML` or `PERCENT` accordingly. For HML type risk score conditions a set of the values `HIGH`, `MEDIUM`, `LOW` or `UNSCORED`, which match entries that fall within the configured risk range for the selected risk score. Here is an example of a HML risk score filter on a custom risk score: ```json theme={null} { "type": "RISK_SCORE", "field": "riskScoresHml", "fieldLabel": "Risk score", "negated": false, "riskScoreType": "HML", "riskScoreId": "risk_67d2f16d9ffead02b4f54aad", "riskScoreLabel": "My custom risk score", "values": [ "MEDIUM", "UNSCORED" ] } ``` For percentage risk score conditions a `riskScorePercentType` of `MORE_THAN`, `LESS_THAN`, `BETWEEN`, `CUSTOM_RANGE` or `UNSCORED` is set. These determine how the rule will be applied, and which parameters can be set. For `UNSCORED` only entries that haven't been scored are matched. For `MORE_THAN` and `LESS_THAN`, a `value` parameter must be set with a number from 0 to 10,000, representing a percentage between 0% to 100%, and matching entries with scores above or below the specified value. For `CUSTOM_RANGE` a pair of percentage values `rangeStart` and `rangeEnd` are set. Any entries whose score falls between the values will be matched. `BETWEEN` is functionally equivalent to custom range, with the restriction that the `rangeStart` and `rangeEnd` must equal the start and end values of one of the risk score's risk range entries (high, medium or low risk). In the web application this is represented as the user selecting an existing risk range, rather than manually entering a pair of percentages as custom range requires. Here is an example of a percentage risk score filter: ```json theme={null} { "type": "RISK_SCORE", "field": "riskScoresPercentage", "fieldLabel": "Risk score", "negated": false, "riskScoreType": "PERCENT", "riskScoreId": "risk", "riskScoreLabel": "MindBridge score", "riskScorePercentType": "MORE_THAN", "value": 0 } ``` #### `MONETARY_FLOW` type condition The `MONETARY_FLOW` type condition matches entries that are part of a monetary flow corresponding to the filter's configuration. This condition type can only be used in general ledger analyses. Only the special case field `monetarySpecificFlow` can be used with this condition type. The property `monetaryFlowType` must be set to one of the following values, which determine what kind of flow to include entries from: `SIMPLE_FLOW`, `COMPLEX_FLOW` or `SPECIFIC_FLOW`. For simple and complex flow values, entries that are part of simple account to account flows, or flows that are too complex to assign to an account are included. For specific flows a pair of credit and debit account selections, `creditAccount` and `debitAccount` accordingly are set. These use the same parameters as the account node array condition. In addition, the code may be set to `complex` to match flows whose credit or debit account is determined to be too complex to match. Additionally for specific flows a value for `specificMonetaryFlowType` must be set, which further filters the entries based on the specific value of the flow. The following values can be used: * `SPECIFIC_VALUE` - by setting the `value` field to a currency amount only entries whose flow amount matches the value exactly will be matched. * `MORE_THAN` - by setting the `value` field to a currency amount only entries where the flow value exceeds that amount will be matched. * `BETWEEN` - a pair of `rangeStart` and `rangeEnd` values only entries whose value is between the specified currency amounts. Currency amounts are expressed as integers, and do not include decimal places. They follow the same formatting rules as `MONEY_100` fields. See the *Data Formats* section for more information. Here is an example of a monetary flow condition: ```json theme={null} { "type": "MONETARY_FLOW", "field": "monetarySpecificFlow", "fieldLabel": "Monetary flow", "negated": false, "monetaryFlowType": "SPECIFIC_FLOW", "creditAccount": { "name": "Flows too complex to determine a match", "code": "complex", "useAccountId": false }, "debitAccount": { "name": "Operational assets", "code": "1100", "useAccountId": false }, "specificMonetaryFlowType": "BETWEEN", "rangeStart": 0, "rangeEnd": 1037979412 } ``` #### `MONEY` type condition The money type condition matches entries whose value for the provided field is within the configured bounds of the condition. The money type condition can be applied to any field with a data table column type of `MONEY_100`. The following `monetaryValueType` values can be used to configure how the entries are matched: * `MORE_THAN` - Matches entries whose value is more than the configured `value` field. * `LESS_THAN` - Matches entries whose value is less than the configured `value` field. * `SPECIFIC_VALUE` - Matches entries whose value is equal to the configured `value` field. * `BETWEEN` - Matches entries whose value is between the provided `rangeStart` and `rangeEnd` values. The values for `value`, `rangeStart` and `rangeEnd` follow the same formatting rules as the `MONEY_100` data type. Here is an example of a money type condition: ```json theme={null} { "type": "MONEY", "field": "bs_delta", "fieldLabel": "Balance sheet impact", "negated": false, "monetaryValueType": "MORE_THAN", "value": 0 } ``` #### `MATERIALITY` type condition The materiality type condition matches entries that are above, below or above a percentage of the threshold. The materiality type condition can be applied to general ledger analyses with a materiality judgment value set, and can only be applied to the special case `materiality` field. The following `materialityOption` values can be used to configure how the entries are matched: * `ABOVE` - Matches entries whose value is above the materiality threshold. * `BELOW` - Matches entries whose value is below the materiality threshold. * `PERCENTAGE` - Matches entries whose value is above a percent of the materiality threshold. The percent is a decimal number set in the `value` field, and can be greater than 100%. Here is an example of a materiality type condition, and represents a percentage value of 110.25%: ```json theme={null} { "type": "MATERIALITY", "field": "materiality", "fieldLabel": "Materiality", "negated": false, "materialityOption": "PERCENTAGE", "value": 110.25 } ``` #### `NUMERICAL` type condition The numerical type condition matches entries whose value for the provided field is within the configured bounds of the condition. This condition can be applied to any field with a data table column types of `INT32`, `INT64`, `FLOAT32` and `FLOAT64`. The following `numericalValueType` values can be used to configure how the entries are matched: * `MORE_THAN` - Matches entries whose value is more than the configured `value` field. * `LESS_THAN` - Matches entries whose value is less than the configured `value` field. * `SPECIFIC_VALUE` - Matches entries whose value is equal to the configured `value` field. * `BETWEEN` - Matches entries whose value is between the provided `rangeStart` and `rangeEnd` values. Here is an example of a numerical type condition: ```json theme={null} { "type": "NUMERICAL", "field": "entries_count", "fieldLabel": "Entries count", "negated": false, "numericalValueType": "MORE_THAN", "value": 0 } ``` #### `DATE` type condition The date type condition matches entries whose value for the provided field is within the configured bounds of the condition. The numerical type condition can be applied to any field with a data table column types of `DATE` and `DATE_TIME`. The following `numericalValueType` values can be used to configure how the entries are matched: * `AFTER` - Matches entries whose value is more than the configured `value` field. * `BEFORE` - Matches entries whose value is less than the configured `value` field. * `SPECIFIC_VALUE` - Matches entries whose value is equal to the configured `value` field. * `BETWEEN` - Matches entries whose value is between the provided `rangeStart` and `rangeEnd` values. The values for `value`, `rangeStart` and `rangeEnd` should be expressed as ISO date strings, without a timestamp or timezone. Here is an example of a date type condition: ```json theme={null} { "type": "DATE", "field": "effective_date", "fieldLabel": "Effective date", "negated": false, "dateType": "SPECIFIC_VALUE", "value": "2010-01-01" } ``` ### Legacy filters Saved filters with the `legacyFilterFormat` field set to `true` are using a legacy format which is not supported by the API, and will have their `condition` property set to `null`. # Task History Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/task-history **Task Histories** are the history entries related to an individual task within the system. # Tasks Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/tasks **Tasks** are data table transactions or entries that have been added to the audit plan for further investigation. # Transaction ID Previews Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/transaction-id-previews **Transaction ID previews** contain the data behind our transaction ID generation and analysis system. In this object, analytic data about a proposed transaction ID is provided to guide the selection of the most appropriate, granular transaction ID, with as few single-entry transactions as possible. An appropriate transaction ID enables MindBridge’s analytics engine to detect anomalies that are more relevant and insightful. # Users Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/users **Users** generally represent you and your team and can be assigned to various roles and tasks within the platform. Users may also represent MindBridge Customer Support staff who are active in customer assistance requests, as well as portal users when connecting integrations and API Token Users. ### User roles User roles determine which actions a user can perform within MindBridge. | Role ID | User Role | Description | | - | - | - | | ROLE\_ADMIN | App Admin | App Admins have full access to the MindBridge tenant. They can invite and manage users, and view/edit all organizations and engagements. | | ROLE\_USER\_ADMIN | User Admin | User Admins can invite and manage tenant users, and create new organizations. | | ROLE\_ORGANIZATION\_ADMIN | Organization Creator | Organization Creators have the same privileges as users, but can also create new organizations. | | ROLE\_USER | User | Users can be invited to existing organizations and engagements, but they cannot create new organizations. | | ROLE\_CLIENT | Client | Clients must be [invited to connect](https://support.mindbridge.ai/hc/en-us/articles/1500001350402) to MindBridge. Once the client account has been activated via email, access is limited to the page that allows them to set up a data source. | | ROLE\_MINDBRIDGE\_SUPPORT | MindBridge Support | MindBridge Support accounts have limited access to engagements, enabling them to assist with specific support requests. | | \* ROLE\_ADMIN and `serviceAccount` equals `true` | API Token User | API Token Users are non-human user accounts linked to unique API tokens. Any action that an API takes will be attributed to this user account. | ### Enabling and disabling users The `enabled` property can be used to enable and disable user accounts within a single tenant. If a user’s account is *disabled*, they will no longer have access to the tenant until they are *enabled*. **Note:** A user who is disabled in one tenant will still be able to access other tenants where they are enabled. ### Account activation emails When a new user is created, they will be sent an **account activation email**. This email contains a link they must use to activate their account. Until the account is activated, the user will not be able to sign in. Activation links expire after 7 days, but additional account activation emails can be sent using the `Resend Activation Link` endpoint. When a user who is `disabled` becomes `enabled` again, they will be sent an activation email. These users must use the account activation link before they can sign in. ### API token permissions The following table details the actions that users of the API may be permitted to take: | Role | Read | Query | Create | Update user enabled status | Update user role | Can update role to | Delete | Can be sent account activation emails | | - | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | | App Admin | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | | User Admin | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Organization Manager | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | User | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Client | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | | MindBridge Support | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | API Token | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | App Admins cannot be deleted, nor have their roles updated. This restriction prevents an API token from accidentally locking out a legitimate administrator, resulting in the loss of administration to the entire tenant. MindBridge Support and API Token Users cannot be created, updated, deleted or sent account activation emails to. These accounts are automatically managed by support access requests and API tokens accordingly. Client users serve a special purpose and cannot be created, nor have their roles updated. These users can only provide access to an integration service. # Webhook event logs Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/webhook-event-logs The webhook event logs provide a way to track events as they are sent by the system, and allow the user to help track messages, or diagnose issues with webhooks. See the webhooks documentation for more information on receiving webhooks, or the webhook section for information about the webhooks themselves. # Webhooks Source: https://developer.mindbridge.ai/api-explorer/tag-descriptions/webhooks The webhooks entity provides a way to configure webhook integrations with other systems. Once created and active webhooks will send event payloads to the configured URL. See the webhooks documentation for more information on receiving webhooks. # Webhooks Source: https://developer.mindbridge.ai/api-explorer/webhooks webhook webhooks Webhooks provide a lightweight, event driven method of notifying external systems of events within the MindBridge platform. Internal events communicate data with external systems via HTTPS requests originating from our platform, allowing for a more robust automation potential without the need to poll for status. In order to leverage webhook functionality, a URL must be provided, and a selection of events that you would like to receive notifications for associated with that URL. ## URL Restrictions - Each webhook must have a unique URL. You can configure a webhook to send multiple events to the same URL. - Must be an HTTPS URL. - The URL hostname must use a fully qualified name, not an IP address. ## Outbound Request Each outbound request is sent as an HTTPS POST. The post will contain a JSON payload in the body of the message. As well as the JSON payload, there are a number of important HTTPS headers that are attached to each message. Using this information, combined with the public key associated with the configured webhook, allows the verification of a digital signature. The method of authenticating the payload will be covered in a separate section. | **HTTPS Header** | **Description** | |---------------------|------------------------------------------------------------------------------------------| | `webhook-id` | A unique event ID for the event that triggered the outbound webhook request. | | `webhook-timestamp` | Timestamp associated with the outbound HTTPS request. | | `webhook-signature` | The digital signature that can be used to validate the authenticity of the webhook data. | ## Security Webhooks operate by communicating with configured HTTPS URLs. This can lead to potential security risks from malicious actors. To authenticate the validity of webhook payloads on the receiving side, the MindBridge platform implements an asymmetric digital signature scheme. This scheme verifies that a payload originated from the platform and has not been modified. When a webhook is registered, a public key utilizing the `Ed25519` algorithm is associated with the webhook configuration. Measures used to mitigate common attack scenarios within the digital signing scheme are covered below. ## Configuring your Server In order to listen to webhook events, you must have a publicly accessible server that can accept HTTPS POST requests from the MindBridge system. This server must not implement any authentication protocols in order to receive data. The data signature scheme implemented provides a mechanism to ensure data integrity, and while this is optional to [authenticate the received payload,](https://mindbridge-ai.atlassian.net/wiki/spaces/SBE/pages/4921327617/API+Content+-+Webhooks#Authenticating-a-Payload "https://mindbridge-ai.atlassian.net/wiki/spaces/SBE/pages/4921327617/API+Content+-+Webhooks#Authenticating-a-Payload") it is highly recommended to utilize this data integrity check in your workflow. ## Responding to Webhook Requests How you respond to a webhook event has implications on the status of the webhook configured within the MindBridge system. We look at the HTTP response code, and in some cases the HTTP headers in order to determine actions we may take within our system. | **HTTP Code** | **Result** | |---------------------|---------------------------------------| | 200 series response | Successfully received webhook payload | ## Authenticating a Payload Use the data from the payload, the headers in the HTTP post, and the public key associated with your webhook configuration. With these, you will be able to validate the digital signature that is attached in the HTTP header. In order to accomplish this, you need to format a string with the following format: `..` Values with `< >` surrounding them are variables to insert into the template above. | **Variable** | **Description** | |-------------------|--------------------------------------------------| | webhook-id | Found in the HTTP header | | webhook-timestamp | Found in the HTTP header | | payload | The unmodified contents of the HTTP POST request | With this string generated, and using the public key from the webhook configuration, and the algorithm `Ed25519`, you can create a digital signature of the formatted string created above, and compare it against the digital signature provided in the HTTP header, under the key `webhook-signature`. The creation of this formatted payload helps to mitigate common attack patterns, such as replay attacks, which is why the timestamp of the outbound request is part of the signed message. ## Events | **Name** | **Description** | **Event Type** | **Payload Model** | |----------------------------------|------------------------------------------------------------------------------------------|----------------------------------|----------------------------------------------| | Analysis Created | An analysis was created. | analysis.created | AnalysisWebhookPayload | | Analysis Updated | An analysis was updated. | analysis.updated | AnalysisWebhookPayload | | Analysis Deleted | An analysis was deleted. | analysis.deleted | AnalysisWebhookPayload | | Analysis Archived | An analysis was archived. | analysis.archived | AnalysisWebhookPayload | | Analysis Unarchived | An analysis was unarchived. | analysis.unarchived | AnalysisWebhookPayload | | Analysis Complete | An analysis completed successfully. | analysis.complete | AnalysisWebhookPayload | | Analysis Failed | An analysis failed. | analysis.failed | AnalysisWebhookPayload | | Engagement Created | An engagement was created. | engagement.created | EngagementWebhookPayload | | Engagement Updated | An engagement was updated. | engagement.updated | EngagementWebhookPayload | | Engagement Deleted | An engagement was deleted. | engagement.deleted | EngagementWebhookPayload | | Unmapped Accounts | An engagement has unresolved account mappings from accounts discovered during ingestion. | unmapped.accounts | EngagementWebhookPayload | | Ingestion Complete | A data ingestion workflow completed. | ingestion.complete | AnalysisSourceWebhookPayload | | Ingestion Failed | A data ingestion workflow failed. | ingestion.failed | AnalysisSourceWebhookPayload | | File Added | A file was added through the file manager. | file.added | FileManagerWebhookPayload | | Connection Data Complete | Asynchronous connection data work finished (for example reading table data). | connection.data.complete | ConnectionAsyncWebhookPayload | | Connection Test Complete | An asynchronous connection test finished. | connection.test.complete | ConnectionAsyncWebhookPayload | | Connection Created | A connection was created. | connection.created | ConnectionLifecycleWebhookPayload | | Connection Deleted | A connection was deleted. | connection.deleted | ConnectionLifecycleWebhookPayload | | Export Ready | A requested file export is ready for download. | export.ready | FileManagerWebhookPayload | | User Invited | A user was invited to the tenant. | user.invited | UserRoleWebhookPayload | | User Role Updated | A user's role was updated. | user.role | UserRoleWebhookPayload | | User Deleted | A user was deleted. | user.deleted | UserWebhookPayload | | User Login | A user logged in. | user.login | UserLoginWebhookPayload | | User Status Updated | A user was enabled or disabled. | user.status | UserStatusWebhookPayload | | MCP Admin Settings Updated | Tenant MCP admin settings changed. See the Activity Report for details. | mcp.admin-settings.updated | McpAdminSettingsWebhookPayload | # Append From Chunked File Source: https://developer.mindbridge.ai/api-reference/account-groupings/append-from-chunked-file /openapi.json post /v1/account-groupings/{accountGroupingId}/append-from-chunked-file Append a chunked file that contains a MindBridge account grouping file (.xlsx) to an existing account grouping to add new account groups and mappings to the existing account grouping. **Note:** Appending to _CCH group trial balance_ files is not supported. ### Permissions - `api.account-groupings.write` # Delete Account Grouping Source: https://developer.mindbridge.ai/api-reference/account-groupings/delete-account-grouping /openapi.json delete /v1/account-groupings/{accountGroupingId} Delete an existing account grouping, identified by its ID. ### Permissions - `api.account-groupings.delete` # Export Account Grouping Source: https://developer.mindbridge.ai/api-reference/account-groupings/export-account-grouping /openapi.json post /v1/account-groupings/{accountGroupingId}/export Export an account grouping and all it’s account groups as an Excel file. Exporting returns an async result, which can then be used to return a file result. ### Permissions - `api.account-groupings.read` # Import From Chunked File Source: https://developer.mindbridge.ai/api-reference/account-groupings/import-from-chunked-file /openapi.json post /v1/account-groupings/import-from-chunked-file Import a chunked file that contains a MindBridge account grouping file (.xlsx) or a _CCH group trial balance_ file to create a new account grouping entry with a complete set of account groups and MAC mappings. The type of file being imported is determined by the `type` property. ### Permissions - `api.account-groupings.write` # Query Account Grouping Source: https://developer.mindbridge.ai/api-reference/account-groupings/query-account-grouping /openapi.json post /v1/account-groupings/query Query account groupings, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` ### Permissions - `api.account-groupings.read` # Read Account Grouping Source: https://developer.mindbridge.ai/api-reference/account-groupings/read-account-grouping /openapi.json get /v1/account-groupings/{accountGroupingId} Read an existing account grouping, identified by its ID. ### Permissions - `api.account-groupings.read` # Update Account Grouping Source: https://developer.mindbridge.ai/api-reference/account-groupings/update-account-grouping /openapi.json put /v1/account-groupings/{accountGroupingId} Update an existing account grouping, identified by its ID. **Note:** If LLM AG Mapping is enabled for the tenant, publishing the account grouping will automatically mark all suggested Mac Code mappings as Verified. ### Permissions - `api.account-groupings.write` # Query Account Group Source: https://developer.mindbridge.ai/api-reference/account-groups/query-account-group /openapi.json post /v1/account-groups/query Query account groups, optionally applying a filter. ## Required Query Restrictions When querying account groups, an `accountGroupingId` field and either an `$eq` or `$in` term must be included. Queries without these restrictions will fail. ### Queryable Fields - `id` - `OBJECT_ID` - `accountGroupingId` - `OBJECT_ID` - `code` - `STRING` ### Permissions - `api.account-groupings.read` # Read Account Group Source: https://developer.mindbridge.ai/api-reference/account-groups/read-account-group /openapi.json get /v1/account-groups/{accountGroupId} Read an existing account group, identified by its ID. ### Permissions - `api.account-groupings.read` # Update Account Group Source: https://developer.mindbridge.ai/api-reference/account-groups/update-account-group /openapi.json put /v1/account-groups/{accountGroupId} Update an existing account group, identified by its ID. ## Lowest level only properties The following properties can only be set on the lowest-level category of each account group: - `macCode` - `accountTags` ### Permissions - `api.account-groupings.write` # Delete Unused Account Mappings For Engagement Source: https://developer.mindbridge.ai/api-reference/account-mappings/delete-unused-account-mappings-for-engagement /openapi.json post /v1/account-mappings/delete-unused Deletes all unused accounts mappings for the provided engagement. ### Permissions - `api.analyses.write` # Export Account Mappings For Engagement Source: https://developer.mindbridge.ai/api-reference/account-mappings/export-account-mappings-for-engagement /openapi.json post /v1/account-mappings/export ### Permissions - `api.analyses.read` # Get Account Mapping Source: https://developer.mindbridge.ai/api-reference/account-mappings/get-account-mapping /openapi.json get /v1/account-mappings/{accountMappingId} Read an existing account mappings, identified by its ID. ### Permissions - `api.analyses.read` # Query Account Mappings Source: https://developer.mindbridge.ai/api-reference/account-mappings/query-account-mappings /openapi.json post /v1/account-mappings/query Query account mappings, optionally applying a filter. ## Required Query Restrictions When querying account groups, an `engagementId` field and either an `$eq` or `$in` term must be included. Queries without these restrictions will fail. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `account` - `STRING` ### Permissions - `api.analyses.read` # Update Account Mapping Source: https://developer.mindbridge.ai/api-reference/account-mappings/update-account-mapping /openapi.json put /v1/account-mappings/{accountMappingId} Update an existing account mapping, identified by its ID. ### Permissions - `api.analyses.write` # Verify Account Mappings For Engagement Source: https://developer.mindbridge.ai/api-reference/account-mappings/verify-account-mappings-for-engagement /openapi.json post /v1/account-mappings/verify Mark all account mappings for a given engagement as verified. ### Permissions - `api.analyses.write` # Run Activity Report Source: https://developer.mindbridge.ai/api-reference/admin-reports/run-activity-report /openapi.json post /v1/admin-reports/activity-report/run Running an **activity report** returns an async result, which can then be used to return a **file result**. Provide `start` and `end` date values to limit the results to a specific time period. Setting values in the `userIds` and `categories` lists will limit the results to the users who performed the actions, and the provided categories, respectively. Leaving these lists empty will return results for all users and categories, respectively. ### Permissions - `api.admin-reports.run` # Run Analysis Overview Report Source: https://developer.mindbridge.ai/api-reference/admin-reports/run-analysis-overview-report /openapi.json post /v1/admin-reports/analysis-overview-report/run Running an **analysis overview report** returns an async result, which can then be used to return a **file result**. ### Permissions - `api.admin-reports.run` # Run Row Usage Report Source: https://developer.mindbridge.ai/api-reference/admin-reports/run-row-usage-report /openapi.json post /v1/admin-reports/row-usage-report/run Running a **row usage report** returns an async result, which can then be used to return a **file result**. ### Permissions - `api.admin-reports.run` # Create Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/create-analysis /openapi.json post /v1/analyses Create a new analysis. If no `reportingPeriodConfigurationId` is provided, it inherits the reporting period set on the engagement. ### Permissions - `api.analyses.write` # Delete Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/delete-analysis /openapi.json delete /v1/analyses/{analysisId} Delete an existing analysis, identified by its ID. ### Permissions - `api.analyses.delete` # Engagement Roll Forward Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/engagement-roll-forward-analysis /openapi.json post /v1/analyses/engagement-roll-forward Roll a completed analysis forward into an existing engagement. This will create a new analysis within the target engagement using the source analysis' data as prior period data for the new analysis. For analyses using a non-periodic time frame, this will create a new current analysis period, with the existing data being added as prior period data. This new current period can be configured to either be a full period, or an interim period. Analyses that use the periodic time frame will be rolled forward into a new periodic time frame, and will not have a new period added. Rolling forward is subject to the following restrictions: - The target engagement must not be the same as the analysis' current engagement. - Only completed analyses can be rolled forward. - Interim analyses cannot be rolled forward. This does not apply to interim analyses that have been converted to full-period analyses. - The library of the target engagement must support the analysis type of the analysis. ### Permissions - `api.analyses.write` # Query Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/query-analysis /openapi.json post /v1/analyses/query Query analyses, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `name` - `STRING` ### Permissions - `api.analyses.read` # Read Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/read-analysis /openapi.json get /v1/analyses/{analysisId} Read an existing analysis, identified by its ID. ### Permissions - `api.analyses.read` # Read Analysis Status Source: https://developer.mindbridge.ai/api-reference/analyses/read-analysis-status /openapi.json get /v1/analyses/{analysisId}/status See a summary of the readiness of an existing analysis, including errors, missing analysis sources and more. ### Permissions - `api.analyses.read` # Run Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/run-analysis /openapi.json post /v1/analyses/{analysisId}/run Run an analysis through MindBridge’s analytics. ### Permissions - `api.analyses.run` # Start Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/start-analysis /openapi.json post /v1/analyses/{analysisId}/start Run an analysis through MindBridge’s analytics. **Deprecation**: This endpoint has been renamed to `/run` and will be removed in a future release. ### Permissions - `api.analyses.run` # Update Analysis Source: https://developer.mindbridge.ai/api-reference/analyses/update-analysis /openapi.json put /v1/analyses/{analysisId} Update an existing analysis, identified by its ID. If no `reportingPeriodConfigurationId` is provided, the existing value will be kept. ### Permissions - `api.analyses.write` # Query Analysis Results Source: https://developer.mindbridge.ai/api-reference/analysis-results/query-analysis-results /openapi.json post /v1/analysis-results/query Query analysis results, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisId` - `OBJECT_ID` ### Permissions - `api.analyses.read` # Read Analysis Result Source: https://developer.mindbridge.ai/api-reference/analysis-results/read-analysis-result /openapi.json get /v1/analysis-results/{analysisResultId} Read an existing analysis result, identified by its ID. ### Permissions - `api.analyses.read` # Query Analysis Source Type Source: https://developer.mindbridge.ai/api-reference/analysis-source-types/query-analysis-source-type /openapi.json post /v1/analysis-source-types/query Query analysis source types, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` ### Permissions - `api.analysis-source-types.read` # Read Analysis Source Type Source: https://developer.mindbridge.ai/api-reference/analysis-source-types/read-analysis-source-type /openapi.json get /v1/analysis-source-types/{analysisSourceTypeId} Read an existing analysis source type, identified by its ID. ### Permissions - `api.analysis-source-types.read` # Create Analysis Source Source: https://developer.mindbridge.ai/api-reference/analysis-sources/create-analysis-source /openapi.json post /v1/analysis-sources Create a new analysis source. ### Permissions - `api.analysis-sources.write` # Delete Analysis Source Source: https://developer.mindbridge.ai/api-reference/analysis-sources/delete-analysis-source /openapi.json delete /v1/analysis-sources/{analysisSourceId} Delete an existing analysis source, identified by its ID. ### Permissions - `api.analysis-sources.delete` # Query Analysis Source Source: https://developer.mindbridge.ai/api-reference/analysis-sources/query-analysis-source /openapi.json post /v1/analysis-sources/query Query analysis sources, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisId` - `OBJECT_ID` - `analysisPeriodId` - `OBJECT_ID` - `analysisSourceTypeId` - `OBJECT_ID` - `additionalDataColumnField` - `STRING` ### Permissions - `api.analysis-sources.read` # Read Analysis Source Source: https://developer.mindbridge.ai/api-reference/analysis-sources/read-analysis-source /openapi.json get /v1/analysis-sources/{analysisSourceId} Read an existing analysis source, identified by its ID. ### Permissions - `api.analysis-sources.read` # Read Effective Date Metrics Source: https://developer.mindbridge.ai/api-reference/analysis-sources/read-effective-date-metrics /openapi.json get /v1/analysis-sources/{analysisSourceId}/effective-date-metrics Query the results of the **Analysis Period** step in the data import process (based on the effective date column), including displaying the histogram by day, week, or month, as well as debit and credit sums for the period and more. ### Permissions - `api.analysis-sources.read` # Update Analysis Source Source: https://developer.mindbridge.ai/api-reference/analysis-sources/update-analysis-source /openapi.json put /v1/analysis-sources/{analysisSourceId} Update an existing analysis source, identified by its ID. ### Permissions - `api.analysis-sources.write` # Query Source: https://developer.mindbridge.ai/api-reference/analysis-type-configuration/query /openapi.json post /v1/analysis-type-configuration/query Query analysis type configurations, optionally applying a filter. ### Queryable fields: - `id` - `OBJECT_ID` - `libraryId` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `controlPointBundleVersion` - `STRING` - `template` - `BOOLEAN` ### Permissions - `api.analysis-type-configuration.read` # Read Source: https://developer.mindbridge.ai/api-reference/analysis-type-configuration/read /openapi.json get /v1/analysis-type-configuration/{analysisTypeConfigurationId} Retrieve an existing analysis type configuration by its ID. ### Permissions - `api.analysis-type-configuration.read` # Update Source: https://developer.mindbridge.ai/api-reference/analysis-type-configuration/update /openapi.json put /v1/analysis-type-configuration/{analysisTypeConfigurationId} Update an existing analysis type configuration by its ID. The configurable properties of an analysis type configuration are grouped into Risk Groups. They can be configured as follows: - Risk groups can be enabled and disabled by setting the `disabled` property. Only engagement-level analysis type configuration can be disabled. - The risk range for use by the risk group can be set by the `selectedRiskRange`, and must also be included in the list of `applicableRiskRanges`. - A `filter` field can optionally be set to limit the risk group to only apply to a set of accounts, rather than all accounts. - The control point weights can be adjusted by setting the value of the `controlPointWeights` key-value map, where the key is the control point's symbolic name. Setting a control point weight to `0` disables the control point within the risk group. Additionally, analysis type configurations cannot be updated if: - The `system` or `template` properties are `true`. - The analysis type configuration is at the analysis level, with a defined `analysisId`. ### Permissions - `api.analysis-type-configuration.write` # Query Analysis Type Source: https://developer.mindbridge.ai/api-reference/analysis-types/query-analysis-type /openapi.json post /v1/analysis-types/query Query analysis types, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` ### Permissions - `api.analysis-types.read` # Read Analysis Type Source: https://developer.mindbridge.ai/api-reference/analysis-types/read-analysis-type /openapi.json get /v1/analysis-types/{analysisTypeId} Read an existing analysis type, identified by its ID. ### Permissions - `api.analysis-types.read` # Create API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/create-api-token /openapi.json post /v1/api-tokens Create a new API token. The creation response will include a `token` field with the newly created token. This token is only returned on creation, and cannot be re-generated afterwards. When an API token is created, an API Token User is automatically created and assigned to the API token. This non-human user account represents the API token, and any action that the API takes will be attributed to that account. The API Token User can be identified through the `userId` property in the API Token entity. ### Permissions - `api.api-tokens.write` # Delete API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/delete-api-token /openapi.json delete /v1/api-tokens/{apiTokenId} Delete an existing API token, identified by its token ID. This will de-authorize the token and automatically delete the associated API Token User. ### Permissions - `api.api-tokens.delete` # Get Current API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/get-current-api-token /openapi.json get /v1/api-tokens/current Read the API token record specified by the API token. This endpoint is not restricted by any permissions and can be used to test the API. # Query API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/query-api-token /openapi.json post /v1/api-tokens/query Query API tokens, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `userId` - `OBJECT_ID` - `name` - `STRING` ### Permissions - `api.api-tokens.read` # Read API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/read-api-token /openapi.json get /v1/api-tokens/{apiTokenId} Read an existing API token, identified by its ID. ### Permissions - `api.api-tokens.read` # Update API Token Source: https://developer.mindbridge.ai/api-reference/api-tokens/update-api-token /openapi.json put /v1/api-tokens/{apiTokenId} Update an existing API token, identified by its ID. ### Permissions - `api.api-tokens.write` # Query Async Result Source: https://developer.mindbridge.ai/api-reference/async-results/query-async-result /openapi.json post /v1/async-results/query Query async results, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `type` - `STRING` - `status` - `STRING` - `entityId` - `OBJECT_ID` - `entityType` - `STRING` ### Permissions This endpoint inherits the permissions from the target entity in scope. For example, if the async result represents an **analysis source**, then the requesting token must contain the permission: `api.analysis-sources.read`. # Read Async Result Source: https://developer.mindbridge.ai/api-reference/async-results/read-async-result /openapi.json get /v1/async-results/{asyncResultId} Read an existing async result, identified by its ID. ### Permissions This endpoint inherits the permissions from the target entity in scope. For example, if the async result represents an **analysis source**, then the requesting token must contain the permission: `api.analysis-sources.read`. # Add Chunked File Part Source: https://developer.mindbridge.ai/api-reference/chunked-files/add-chunked-file-part /openapi.json post /v1/chunked-files/{chunkedFileId}/part This endpoint is used to append a `chunkedFilePart` to a chunked file. Chunked file parts must provide an `offset` and a `size` along with content. The first chunked file part must have offset `0`. You may add the same chunked file part multiple times to retry a failed import. When retrying, you must use the same `offset` and `size`. You may add chunked file parts out of order. - Maximum chunked file part size: 50 MiB. - Maximum number of chunked file parts in one file: 1000. - Maximum overall file size: 20 GiB. The body of the request is an HTTP form with the `Content-Type` header set to `multipart/form-data`, and contains 2 parts: `chunkedFilePart` for the **chunk properties**, and `fileChunk` for the **data**. The `chunkedFilePart` must have the `Content-Type` header set to `application/json` and is similar to other entity types. It specifies the `offset` and `size` of the chunk. The fileChunk contains the file to be imported. Its `Content-Type` header must correspond to the file’s data type. For example, for a `.csv` file, the `Content-Type` header for the `fileChunk` should be `text/csv`. ### Permissions - `api.file-manager.write` # Create Chunked File Source: https://developer.mindbridge.ai/api-reference/chunked-files/create-chunked-file /openapi.json post /v1/chunked-files This endpoint allows you to begin the process of importing a file in multiple chunks. Calling this endpoint returns a `{chunkedFileId}` to use in subsequent steps. ### Permissions - `api.file-manager.write` # Delete Chunked File Source: https://developer.mindbridge.ai/api-reference/chunked-files/delete-chunked-file /openapi.json delete /v1/chunked-files/{chunkedFileId} Deletes a pending chunked file import, identified by its ID. ### Permissions - `api.file-manager.delete` # Query Chunked File Source: https://developer.mindbridge.ai/api-reference/chunked-files/query-chunked-file /openapi.json post /v1/chunked-files/query Queries a pending chunked file import, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `name` - `STRING` ### Permissions - `api.file-manager.read` # Read Chunked File Source: https://developer.mindbridge.ai/api-reference/chunked-files/read-chunked-file /openapi.json get /v1/chunked-files/{chunkedFileId} Returns the state of a pending chunked file import, identified by its ID. ### Permissions - `api.file-manager.read` # Query Connection Tables Results Source: https://developer.mindbridge.ai/api-reference/connection-tables-results/query-connection-tables-results /openapi.json post /v1/connection-tables-results/query Query connection tables results, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `connectionId` - `OBJECT_ID` ### Permissions - `api.connections.read` # Read Connection Tables Result Source: https://developer.mindbridge.ai/api-reference/connection-tables-results/read-connection-tables-result /openapi.json get /v1/connection-tables-results/{connectionTablesResultId} Read an existing connection tables result, identified by its ID. ### Permissions - `api.connections.read` # Query Connection Test Results Source: https://developer.mindbridge.ai/api-reference/connection-test-results/query-connection-test-results /openapi.json post /v1/connection-test-results/query Query connection test results, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `connectionId` - `OBJECT_ID` ### Permissions - `api.connections.read` # Read Connection Test Result Source: https://developer.mindbridge.ai/api-reference/connection-test-results/read-connection-test-result /openapi.json get /v1/connection-test-results/{connectionTestResultId} Read an existing connection test result, identified by its ID. ### Permissions - `api.connections.read` # Create Connection Source: https://developer.mindbridge.ai/api-reference/connections/create-connection /openapi.json post /v1/connections Create a new connection. ### Permissions - `api.connections.write` # Delete Connection Source: https://developer.mindbridge.ai/api-reference/connections/delete-connection /openapi.json delete /v1/connections/{connectionId} Delete an existing connection, identified by its ID. ### Permissions - `api.connections.delete` # Get Data For Connection Source: https://developer.mindbridge.ai/api-reference/connections/get-data-for-connection /openapi.json post /v1/connections/{connectionId}/get-data Retrieve data from a specific table in an existing connection. Requires a request body specifying the table, engagement, and optional schema hint, filter, and pagination parameters. Returns an async result that can be polled for the data retrieval outcome. On success, the retrieved data is stored as a Data Table entity. ### Permissions - `api.connections.read` - `api.data-tables.write` # Get Tables For Connection Source: https://developer.mindbridge.ai/api-reference/connections/get-tables-for-connection /openapi.json post /v1/connections/{connectionId}/tables Retrieve the list of available tables from an existing connection, identified by its ID. Returns an async result that can be polled for the table discovery outcome. ### Permissions - `api.connections.read` # Query Connection Source: https://developer.mindbridge.ai/api-reference/connections/query-connection /openapi.json post /v1/connections/query Query connections, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `type` - `STRING` ### Permissions - `api.connections.read` # Read Connection Source: https://developer.mindbridge.ai/api-reference/connections/read-connection /openapi.json get /v1/connections/{connectionId} Read an existing connection, identified by its ID. ### Permissions - `api.connections.read` # Test Connection Source: https://developer.mindbridge.ai/api-reference/connections/test-connection /openapi.json post /v1/connections/{connectionId}/test Test an existing connection, identified by its ID. Returns an asynchronous result that can be polled for the test outcome. ### Permissions - `api.connections.read` # Create Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/create-data-catalog-entry /openapi.json post /v1/data-catalog-entries Create a new data catalog entry. Data catalog entries must provide a value for the `source` field, and depending on the value used the following values are required: - When the `source` field is set to `DATA_TABLE` the `dataTableId` field must be set to the ID of a data table accessible by the API. - When the `source` field is set to `CONNECTION`, both `connectionId` and `tableId` must be set. ### Permissions - `api.data-catalog-entries.write` # Delete Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/delete-data-catalog-entry /openapi.json delete /v1/data-catalog-entries/{dataCatalogEntryId} Delete an existing data catalog entry, identified by its ID. ### Permissions - `api.data-catalog-entries.delete` # Get Data For Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/get-data-for-data-catalog-entry /openapi.json post /v1/data-catalog-entries/{dataCatalogEntryId}/get-data Imports the data from a data catalog entry into MindBridge, asynchronously creating a new data table. The request can specify which columns to import, and can optionally provide a filter, a limit, an offset, and a set of sort properties to be applied when importing the data. The data catalog entry’s source will be updated and validated before importing any data to ensure that the schema in the data catalog entry and the request are valid. If either the data catalog entry or the request are not valid, then the request will fail. Unlike the Validate endpoint, for `CONNECTION` sources this endpoint does not need to call the `Get Tables For Connection` endpoint, as the underlying connection table will be refreshed directly before validation. Note that the data catalog entry's own column definitions are not automatically updated from the connection — they reflect the schema at the time the entry was created. ### Permissions - `api.data-catalog-entries.read` - `api.data-tables.write` # Query Data Catalog Entries Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/query-data-catalog-entries /openapi.json post /v1/data-catalog-entries/query Query data catalog entry, optionally applying a filter. ### Queryable Fields - `id` - `OBJECTID` - `source` - `STRING` ### Permissions - `api.data-catalog-entries.read` # Read Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/read-data-catalog-entry /openapi.json get /v1/data-catalog-entries/{dataCatalogEntryId} Read an existing data catalog entry, identified by its ID. ### Permissions - `api.data-catalog-entries.read` # Update Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/update-data-catalog-entry /openapi.json put /v1/data-catalog-entries/{dataCatalogEntryId} Update an existing data catalog entry, identified by its ID. ### Permissions - `api.data-catalog-entries.write` # Validate Data Catalog Entry Source: https://developer.mindbridge.ai/api-reference/data-catalog-entries/validate-data-catalog-entry /openapi.json post /v1/data-catalog-entries/{dataCatalogEntryId}/validate Validates that the schema of the data catalog entry aligns with the schema of its source. In the case of `CONNECTION` sourced data catalog entries the connection may need to be refreshed before running validate to ensure that the most current schema of the remote data table is being validated against. This can be done by calling the `Get Tables For Connection` endpoint, which will update all tables related to that connection. ### Permissions - `api.data-catalog-entries.read` # Query Connection Tables Source: https://developer.mindbridge.ai/api-reference/data-connection-tables/query-connection-tables /openapi.json post /v1/connection-tables/query Query connection tables, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `tablesResultId` - `OBJECT_ID` - `connectionId` - `OBJECT_ID` - `tableId` - `STRING` ### Permissions - `api.connections.read` # Read Connection Tables Source: https://developer.mindbridge.ai/api-reference/data-connection-tables/read-connection-tables /openapi.json get /v1/connection-tables/{connectionTableId} Read an existing connection table, identified by its ID. ### Permissions - `api.connections.read` # Create Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/create-data-flow /openapi.json post /v1/data-flows Create a new data flow. ### Permissions - `api.data-catalog-entries.write` # Delete Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/delete-data-flow /openapi.json delete /v1/data-flows/{dataFlowId} Delete an existing data flow, identified by its ID. ### Permissions - `api.data-catalog-entries.delete` # Get Data For Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/get-data-for-data-flow /openapi.json post /v1/data-flows/{dataFlowId}/get-data Imports the data from a data flow into MindBridge, asynchronously creating a new data table. The request can specify which columns to import, and can optionally provide a filter, a limit, an offset, and a set of sort properties to be applied when importing the data. The data flow’s upstream data catalog will be updated and validated before importing any data to ensure that the schema in the data flow and the request are valid. If either the data flow definition or the request are not valid, then the request will fail. ### Permissions - `api.data-catalog-entries.read` - `api.data-tables.write` # Query Data Flows Source: https://developer.mindbridge.ai/api-reference/data-flows/query-data-flows /openapi.json post /v1/data-flows/query Query data flows, optionally applying a filter. ### Permissions - `api.data-catalog-entries.read` # Read Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/read-data-flow /openapi.json get /v1/data-flows/{dataFlowId} Read an existing data flow, identified by its ID. ### Permissions - `api.data-catalog-entries.read` # Update Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/update-data-flow /openapi.json put /v1/data-flows/{dataFlowId} Update an existing data flow, identified by its ID. ### Permissions - `api.data-catalog-entries.write` # Validate Data Flow Source: https://developer.mindbridge.ai/api-reference/data-flows/validate-data-flow /openapi.json post /v1/data-flows/{dataFlowId}/validate Validates a provided data query against an existing data flow, returning a list of errors caused by incompatibilities or mis-configuration of the query, the data flow, or any sources that are used as part of the data flow. Note that this does not update any schemas, such as connection tables, so users may need to use the appropriate endpoint to update those schemas to the latest version before validation. ### Permissions - `api.data-catalog-entries.read` # Query Data Source Import Tasks Source: https://developer.mindbridge.ai/api-reference/data-source-import-tasks/query-data-source-import-tasks /openapi.json post /v1/data-source-import-tasks/query Query data source import tasks, optionally applying a filter. ### Queryable Fields - `id` - `OBJECTID` - `engagementId` - `OBJECTID` - `state` - `STRING` - `type` - `STRING` - `dataSourceId`- `OBJECTID` - `outputDataTableId` - `OBJECTID` ### Permissions - `api.data-catalog-entries.read` # Read Data Source Import Task Source: https://developer.mindbridge.ai/api-reference/data-source-import-tasks/read-data-source-import-task /openapi.json get /v1/data-source-import-tasks/{dataSourceImportTaskId} Read an existing data source import task, identified by its ID. ### Permissions - `api.data-catalog-entries.read` # Export Data Table Source: https://developer.mindbridge.ai/api-reference/data-tables/export-data-table /openapi.json post /v1/data-tables/{dataTableId}/export Export a data table as a CSV. Exporting returns an async result, which can then be used to return a file result. ### CSV Formatting By default, the following CSV formatting is used: - Comma (`,`) is used as the separator - Double quotes (`"`) are used as the quote character - Double quotes (`"`) are used as the quote escape character: (`""`) - No quote escape escape value is set, as it is not needed - All headers and values are quoted The CSV formatting rules can be customized by setting the `csvConfiguration` field. Any values that are not changed will use their default value. It is strongly recommended to not use newline or whitespace characters, or to use the same characters for both the separator and quote characters, as they may produce files that can't be read correctly. ### Inner lists `ARRAY_STRINGS` type fields are formatted as a CSV value. By default, they have the following formatting: - Semicolon (`;`) is used as the separator - Single quotes (`'`) are used as the quote character - Single quotes (`'`) are used as the quote escape character: (`''`) - No quote escape escape value is set, as it is not needed - All values are quoted In addition to the same recommendations as with CSV formatting it is also strongly recommended to not use the same characters for formatting inner lists as are used for CSV formatting, as it may produce a file that can't be read correctly. ### Flag type formatting `BOOLEAN_FLAGS`, `MAP_SCALARS`, and `LEGACY_ACCOUNT_TAG_EFFECTS` type fields are split into multiple columns based on the column's flags. The field names will be formatted in the following way: `{field}_{flag}`. ### Query Restrictions Columns with type `KEYWORD_SEARCH` or the `filterOnly` property set to `true` can't be included in data table exports. Attempting to select them as part of `fields` will cause the export request to fail. ### Sorting Restrictions When a `sort` is provided in the request body, it will only apply to data table exports under 2 million rows. For exports over 2 million rows, no sorting will be applied to improve performance. ### Permissions - `api.data-tables.read` # Query Data Table Source: https://developer.mindbridge.ai/api-reference/data-tables/query-data-table /openapi.json post /v1/data-tables/query Query data tables, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisId` - `OBJECT_ID` - `analysisResultId` - `OBJECT_ID` - `logicalName` - `STRING` - `type` - `STRING` ### Permissions - `api.data-tables.read` # Query Data Table Data Source: https://developer.mindbridge.ai/api-reference/data-tables/query-data-table-data /openapi.json post /v1/data-tables/{dataTableId}/data This endpoint allows you to load data from the data table. This data is retrieved as pages and can be sorted and filtered by a MindBridge QL query. ## 423 Locked – Response Code MindBridge automatically loads data table results into fast storage for querying. If you receive an **HTTP 423** response code while querying a table, it means MindBridge is retrieving your data. Wait a few seconds before trying again. ## Paging for tables without a primary key Some data tables, such as those loaded from a data connection, do not have a primary key. These tables are paged using a simple offset and limit rather than the optimized cursor used for other tables. As a result: - Ordering is not guaranteed to be stable across requests unless you supply a `sort`. Sorting on a column that contains duplicate values may still produce an inconsistent order between pages. - Requesting deep pages may be slower. For consistent results, supply a `sort` on a column with unique values. ## Filter-only fields Filter-only fields cannot be included in the `fields` or `sort` properties in a data table query, but they can be included in the `query` property. ## Populations If supported by your analysis, data table entries can be filtered by population, and can include an additional column to indicate all populations that the entry appears within. To include or exclude entries by population, use the `$population` and `$not_population` operators as part of the `query`. For example, if you had a population with ID `"643eff00ec992f7ec42ed9f7"`, you could filter for all entries that appear within the population. ```json { "query": { "$population": "643eff00ec992f7ec42ed9f7" }, "fields": [ "rowid", "txid", "debit", "credit" ] } ``` To include a list of populations that each entry is part of, add the `"populations"` column to the `fields` parameter. **Note**: You cannot use the `population` field as part of a query — instead, use the `$population` and `$not_population` operators. For example, the following body will include the `populations` column: ```json { "query": {}, "fields": [ "rowid", "txid", "populations", "debit", "credit" ] } ``` ### Permissions - `api.data-tables.read` # Read Data Table Source: https://developer.mindbridge.ai/api-reference/data-tables/read-data-table /openapi.json get /v1/data-tables/{dataTableId} Read an existing data table, identified by its ID. ### Permissions - `api.data-tables.read` # Create Gdpdu Unpack Job Source: https://developer.mindbridge.ai/api-reference/data-transformation/create-gdpdu-unpack-job /openapi.json post /v1/file-manager/transform/gdpdu-unpack Unpack and format the data files in a GDPdU archive stored in the File Manager. Returns an async result whose target is the created GDPdU Unpack Job. ### Permissions - `api.file-manager.write` # Create Merge File Job Source: https://developer.mindbridge.ai/api-reference/data-transformation/create-merge-file-job /openapi.json post /v1/file-manager/transform/merge Merge data from the first sheet of multiple file manager files, then generate a new file with all source data on a single sheet. Preferred field (new): `mappings` — a list of objects, each with a `fileManagerFileId` and a `columns` array that defines how its columns map into the merged output positions. Example (`mappings`): ``` { "mappings": [ {"fileManagerFileId": "1234567890abcdef12345678", "columns": [0, 1, 2, 3, 4]}, {"fileManagerFileId": "2345678901bcdefa23456789", "columns": [1, 0, 2, 4, 3]} ] } ``` Deprecated (legacy) field: `fileColumnMappings` — a map from `fileManagerFileId` to its columns array. It is still accepted for backward compatibility but will be removed in a future version. Example (`fileColumnMappings`): ``` { "fileColumnMappings": { "1234567890abcdef12345678": [0, 1, 2, 3, 4], "2345678901bcdefa23456789": [1, 0, 2, 4, 3] } } ``` The first mapping entry (in either format) is the master/template file and its columns array defines the output column positions. Columns are numbered from left to right, with the leftmost in a file being position 0. Each subsequent entry defines, for each output column, which column index to use from that file, allowing flexible mapping and positioning in the merged result. ### Permissions - `api.file-manager.write` # Create Databricks Authorization Source: https://developer.mindbridge.ai/api-reference/databricks-authorization/create-databricks-authorization /openapi.json post /v1/databricks-auth Create a new Databricks authorization. ### Permissions - `api.connections.write` # Delete Databricks Authorization Source: https://developer.mindbridge.ai/api-reference/databricks-authorization/delete-databricks-authorization /openapi.json delete /v1/databricks-auth/{authorizationId} Delete an existing Databricks authorization, identified by its ID. ### Permissions - `api.connections.write` # Get Databricks Authorization Source: https://developer.mindbridge.ai/api-reference/databricks-authorization/get-databricks-authorization /openapi.json get /v1/databricks-auth/{authorizationId} Read an existing Databricks authorization, identified by its ID. ### Permissions - `api.connections.read` # Query Databricks Authorizations Source: https://developer.mindbridge.ai/api-reference/databricks-authorization/query-databricks-authorizations /openapi.json post /v1/databricks-auth/query Query Databricks authorizations, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `connectionId` - `OBJECT_ID` ### Permissions - `api.connections.read` # Update Databricks Authorization Source: https://developer.mindbridge.ai/api-reference/databricks-authorization/update-databricks-authorization /openapi.json put /v1/databricks-auth Update an existing Databricks authorization. ### Permissions - `api.connections.write` # Export Engagement Account Grouping Source: https://developer.mindbridge.ai/api-reference/engagement-account-groupings/export-engagement-account-grouping /openapi.json post /v1/engagement-account-groupings/{engagementAccountGroupingId}/export Export an engagement account grouping and all of its account groups as an Excel file. Exporting returns an async result, which can then be used to return a file result. ### Permissions - `api.engagement-account-groupings.read` # Query Engagement Account Grouping Source: https://developer.mindbridge.ai/api-reference/engagement-account-groupings/query-engagement-account-grouping /openapi.json post /v1/engagement-account-groupings/query Query engagement account groupings, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `accountGroupingId` - `OBJECT_ID` ### Permissions - `api.engagement-account-groupings.read` # Read Engagement Account Grouping Source: https://developer.mindbridge.ai/api-reference/engagement-account-groupings/read-engagement-account-grouping /openapi.json get /v1/engagement-account-groupings/{engagementAccountGroupingId} Read an existing engagement account grouping, identified by its ID. ### Permissions - `api.engagement-account-groupings.read` # Create Engagement Account Group Source: https://developer.mindbridge.ai/api-reference/engagement-account-groups/create-engagement-account-group /openapi.json post /v1/engagement-account-groups Create a new engagement account group. New engagement account groups must adhere to the following conditions: - The provided code must be unique within the engagement account grouping. - An engagement account group can have no more than three parents in its hierarchy. Setting an engagement account group's parent code such that it would have more than three parents is not allowed. - Lowest level engagement account groups must include a valid MAC code. - Engagement account groups cannot be added to a MAC account grouping. ### Permissions - `api.engagement-account-groupings.write` # Delete Engagement Account Group Source: https://developer.mindbridge.ai/api-reference/engagement-account-groups/delete-engagement-account-group /openapi.json delete /v1/engagement-account-groups/{engagementAccountGroupId} Delete an existing engagement account group by its ID. The following restrictions apply when deleting engagement account groups: - Engagement account groups that are in use by an account mapping, or have child groups that are in use, cannot be deleted. - Engagement account groups derived from a library-level account grouping cannot be deleted. - Engagement account groups that are part of a MAC account grouping cannot be deleted. ### Permissions - `api.engagement-account-groupings.write` # Query Engagement Account Groups Source: https://developer.mindbridge.ai/api-reference/engagement-account-groups/query-engagement-account-groups /openapi.json post /v1/engagement-account-groups/query Query engagement account groups, optionally applying a filter. ### Required Query Restrictions When querying engagement account groups, an `engagementAccountGroupingId` field and either an `$eq` or `$in` term must be included. Queries without these restrictions will fail. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementAccountGroupingId` - `OBJECT_ID` - `hidden` - `BOOLEAN` - `code` - `STRING` ### Permissions - `api.engagement-account-groupings.read` # Read Engagement Account Group Source: https://developer.mindbridge.ai/api-reference/engagement-account-groups/read-engagement-account-group /openapi.json get /v1/engagement-account-groups/{engagementAccountGroupId} Read an existing engagement account group, identified by its ID. ### Permissions - `api.engagement-account-groupings.read` # Update Engagement Account Group Source: https://developer.mindbridge.ai/api-reference/engagement-account-groups/update-engagement-account-group /openapi.json put /v1/engagement-account-groups/{engagementAccountGroupId} Update an existing engagement account group by its ID. Updates to existing engagement account groups must adhere to the following conditions: - Engagement account groups cannot be hidden or have their code changed if they are in use. - Updated codes must be unique within the engagement account grouping. - In order to ensure the integrity of the balance sheet and income statement MAC codes in the 1000, 2000, or 3000 range cannot be changed to codes in the 4000 or 5000 range, and vice versa. - Engagement account groups that are part of a MAC account grouping cannot be updated. ### Permissions - `api.engagement-account-groupings.write` # Create Engagement Source: https://developer.mindbridge.ai/api-reference/engagements/create-engagement /openapi.json post /v1/engagements Create a new engagement. ### Permissions - `api.engagements.write` # Delete Engagement Source: https://developer.mindbridge.ai/api-reference/engagements/delete-engagement /openapi.json delete /v1/engagements/{engagementId} Delete an existing engagement, identified by its ID. ### Permissions - `api.engagements.delete` # Query Engagement Source: https://developer.mindbridge.ai/api-reference/engagements/query-engagement /openapi.json post /v1/engagements/query Query engagements, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `organizationId` - `OBJECT_ID` - `name` - `String` - `billingCode` - `String` - `libraryId` - `OBJECT_ID` - `engagementLeadId` - `OBJECT_ID` ### Permissions - `api.engagements.read` # Read Engagement Source: https://developer.mindbridge.ai/api-reference/engagements/read-engagement /openapi.json get /v1/engagements/{engagementId} Read an existing engagement, identified by its ID. ### Permissions - `api.engagements.read` # Update Engagement Source: https://developer.mindbridge.ai/api-reference/engagements/update-engagement /openapi.json put /v1/engagements/{engagementId} Update an existing engagement, identified by its ID. ### Permissions - `api.engagements.write` # Get File Info Source: https://developer.mindbridge.ai/api-reference/file-info/get-file-info /openapi.json get /v1/file-infos/{fileInfoId} Read an existing file info, identified by its ID. ### Permissions - `api.file-infos.read` # Query File Info Source: https://developer.mindbridge.ai/api-reference/file-info/query-file-info /openapi.json post /v1/file-infos/query Query file infos, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `type` - `TEXT` ### Permissions - `api.file-infos.read` # Create File Manager Directory Source: https://developer.mindbridge.ai/api-reference/file-manager/create-file-manager-directory /openapi.json post /v1/file-manager Create a new file manager directory. ### Permissions - `api.file-manager.write` # Create File Manager File From Chunked File Source: https://developer.mindbridge.ai/api-reference/file-manager/create-file-manager-file-from-chunked-file /openapi.json post /v1/file-manager/create-from-chunked-file This endpoint validates that all chunks of the import have been received, then completes a chunked file import, given by its ID in the message body, and creates a **file manager file** entity. ### Permissions - `api.file-manager.write` # Create File Manager File From Chunked File (deprecated) Source: https://developer.mindbridge.ai/api-reference/file-manager/create-file-manager-file-from-chunked-file-deprecated /openapi.json post /v1/file-manager/import-from-chunked/{chunkedFileId} This endpoint validates that all chunks of the import have been received, then completes a chunked file import, given by its ID in the URL, and creates a **file manager file** entity. ### Permissions - `api.file-manager.write` # Create File Manager File From Multipart File Source: https://developer.mindbridge.ai/api-reference/file-manager/create-file-manager-file-from-multipart-file /openapi.json post /v1/file-manager/import This endpoint allows you to import a file and set the properties of the resulting File Manager File entity at the same time. The body of the request is an HTTP form with the `Content-Type` header set to `multipart/form-data`, containing 2 parts: `fileManagerFile` for the **entity properties**, and `file` for the **file**. The `fileManagerFile` part must have the `Content-Type` header set to `application/json` and is similar to other entity types. The `file` part contains the file to be uploaded and its `Content-Type` header must correspond to the file’s data type. For example, for a `.csv` file, the `Content-Type` header for the file part should be `text/csv`. For reference, these are the content types associated with common file types: | File extension | Content type value | |----------------|---------------------------------------------------------------------| | `.csv` | `text/csv` | | `.xls` | `application/vnd.ms-excel` | | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | | `.zip` | `application/zip` | | `.gz` | `application/gzip` | ### Permissions - `api.file-manager.write` # Delete File Manager Entity Source: https://developer.mindbridge.ai/api-reference/file-manager/delete-file-manager-entity /openapi.json delete /v1/file-manager/{fileManagerEntityId} Delete an existing **file manager entity**, identified by its ID. ### Permissions - `api.file-manager.delete` # Export File Manager File Source: https://developer.mindbridge.ai/api-reference/file-manager/export-file-manager-file /openapi.json get /v1/file-manager/{fileManagerFileId}/export Export an existing **file manager file**, identified by its ID. ### Permissions - `api.file-manager.read` # Import From Data Table Source: https://developer.mindbridge.ai/api-reference/file-manager/import-from-data-table /openapi.json post /v1/file-manager/import-from-data-table Create a new file manager file by exporting data from a data table. The resulting file will be a CSV file placed in the specified file manager directory. Returns an async result that can be polled for the export outcome. Requires both `API_DATA_TABLES_READ` and `API_FILE_MANAGER_WRITE` permissions. ### Permissions - `api.file-manager.write` # Import From Json Table Source: https://developer.mindbridge.ai/api-reference/file-manager/import-from-json-table /openapi.json post /v1/file-manager/import-from-json-table Create a new file manager file from the imported parts of a JSON table. The resulting file will be a CSV file, and headers will appear in the same order as the original source. ### Permissions - `api.file-manager.write` # Query File Manager Entity Source: https://developer.mindbridge.ai/api-reference/file-manager/query-file-manager-entity /openapi.json post /v1/file-manager/query Query **file manager entities**, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `type` - `STRING` - `engagementId` - `OBJECT_ID` - `parentFileManagerEntityId` - `OBJECT_ID` - `name` - `STRING` - `originalName` - `STRING` ### Permissions - `api.file-manager.read` # Read File Manager Entity Source: https://developer.mindbridge.ai/api-reference/file-manager/read-file-manager-entity /openapi.json get /v1/file-manager/{fileManagerEntityId} Read an existing **file manager entity**, identified by its ID. ### Permissions - `api.file-manager.read` # Update File Manager Entity Source: https://developer.mindbridge.ai/api-reference/file-manager/update-file-manager-entity /openapi.json put /v1/file-manager/{fileManagerEntityId} Update an existing **file manager entity**, identified by its ID. ### Permissions - `api.file-manager.write` # Export File Result Source: https://developer.mindbridge.ai/api-reference/file-results/export-file-result /openapi.json get /v1/file-results/{fileResultId}/export Export a file result, identified by its ID. # Query File Result Source: https://developer.mindbridge.ai/api-reference/file-results/query-file-result /openapi.json post /v1/file-results/query Query file results, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `fileName` - `STRING` # Read File Result Source: https://developer.mindbridge.ai/api-reference/file-results/read-file-result /openapi.json get /v1/file-results/{fileResultId} Read an existing file result, identified by its ID. # Query Gdpdu Unpack Job Source: https://developer.mindbridge.ai/api-reference/gdpdu-unpack-jobs/query-gdpdu-unpack-job /openapi.json post /v1/gdpdu-unpack-jobs/query Query GDPdU unpack jobs, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `fileManagerFileId` - `OBJECT_ID` ### Permissions - `api.file-manager.read` # Read Gdpdu Unpack Job Source: https://developer.mindbridge.ai/api-reference/gdpdu-unpack-jobs/read-gdpdu-unpack-job /openapi.json get /v1/gdpdu-unpack-jobs/{gdpduUnpackJobId} Read a GDPdU unpack job, identified by its ID. ### Permissions - `api.file-manager.read` # Append Source: https://developer.mindbridge.ai/api-reference/json-tables/append /openapi.json post /v1/json-tables/{jsonTableId}/append Append data to an existing JSON table. This should not be run in parallel with another append call, or when creating a file manager file, as undefined behaviour may occur. ### Permissions - `api.file-manager.write` # Create Source: https://developer.mindbridge.ai/api-reference/json-tables/create /openapi.json post /v1/json-tables Create a new JSON table. ### Permissions - `api.file-manager.write` # Read Json Table Source: https://developer.mindbridge.ai/api-reference/json-tables/read-json-table /openapi.json get /v1/json-tables/{jsonTableId} Read an existing JSON Table, identified by its ID. ### Permissions - `api.file-manager.read` # Create Library Source: https://developer.mindbridge.ai/api-reference/libraries/create-library /openapi.json post /v1/libraries Create a new library. If the selected account grouping and the account grouping associated with the selected base library are different, MindBridge can attempt to convert the settings (e.g., ratios, filters, populations, etc.) from the base library for use with the accounts in the selected account grouping. To do so, set the `convertSettings` property to `true` — any accounts that cannot be converted will be listed in the `conversionWarnings` field. **Note**: If `warningsDismissed` is also set to `true`, these warnings will not be displayed in the UI. Restrictions - The industry tags for the new library must be included in the selected account grouping. ### Permissions - `api.libraries.write` # Delete Library Source: https://developer.mindbridge.ai/api-reference/libraries/delete-library /openapi.json delete /v1/libraries/{libraryId} Delete an existing library, identified by its ID. Restrictions * System libraries cannot be deleted. * Libraries in use by engagements cannot be deleted. * Libraries that are used as the basis of other libraries cannot be deleted. ### Permissions - `api.libraries.delete` # Query Library Source: https://developer.mindbridge.ai/api-reference/libraries/query-library /openapi.json post /v1/libraries/query Query libraries, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `basedOnLibraryId` - `OBJECT_ID` - `originalSystemLibraryId` - `OBJECT_ID` - `accountGroupingId` - `OBJECT_ID` - `system` - `BOOLEAN` - `archived` - `BOOLEAN` ### Permissions - `api.libraries.read` # Read Library Source: https://developer.mindbridge.ai/api-reference/libraries/read-library /openapi.json get /v1/libraries/{libraryId} Read an existing library, identified by its ID. ### Permissions - `api.libraries.read` # Update Library Source: https://developer.mindbridge.ai/api-reference/libraries/update-library /openapi.json put /v1/libraries/{libraryId} Update an existing library, identified by its ID. Restrictions - System libraries cannot be updated. ### Permissions - `api.libraries.write` # Create Organization Source: https://developer.mindbridge.ai/api-reference/organizations/create-organization /openapi.json post /v1/organizations Create a new organization. ### Permissions - `api.organizations.write` # Delete Organization Source: https://developer.mindbridge.ai/api-reference/organizations/delete-organization /openapi.json delete /v1/organizations/{organizationId} Delete an existing organization, identified by its ID. ### Permissions - `api.organizations.delete` # Query Organization Source: https://developer.mindbridge.ai/api-reference/organizations/query-organization /openapi.json post /v1/organizations/query Query organizations, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `name` - `STRING` - `externalClientCode` - `STRING` ### Permissions - `api.organizations.read` # Read Organization Source: https://developer.mindbridge.ai/api-reference/organizations/read-organization /openapi.json get /v1/organizations/{organizationId} Read an existing organization, identified by its ID. ### Permissions - `api.organizations.read` # Update Organization Source: https://developer.mindbridge.ai/api-reference/organizations/update-organization /openapi.json put /v1/organizations/{organizationId} Update an existing organization, identified by its ID. ### Permissions - `api.organizations.write` # Create Population Source: https://developer.mindbridge.ai/api-reference/populations/create-population /openapi.json post /v1/populations Create a new population. Engagement populations cannot be created directly, they can only be promoted from an analysis population, or inherited from a library population. ### Permissions - `api.libraries.write` - `api.analyses.write` # Delete Population Source: https://developer.mindbridge.ai/api-reference/populations/delete-population /openapi.json delete /v1/populations/{populationTagId} Delete a population, identified by its ID. Engagement populations cannot be deleted. ### Permissions - `api.libraries.delete` - `api.analyses.delete` # Query Populations Source: https://developer.mindbridge.ai/api-reference/populations/query-populations /openapi.json post /v1/populations/query Query populations, optionally applying a filter. ### Queryable Fields - `id - OBJECT_ID` - `libraryId - OBJECT_ID` - `disabledForAnalysisIds - List` - `promotedFromAnalysisId - OBJECT_ID` - `engagementId - OBJECT_ID` - `analysisId - OBJECT_ID` - `derivedFromEngagement - BOOLEAN` - `basePopulationId - OBJECT_ID` - `name - STRING` - `category - STRING` - `disabled - BOOLEAN` ### Permissions - `api.libraries.read` - `api.engagements.read` - `api.analyses.read` # Read Population Source: https://developer.mindbridge.ai/api-reference/populations/read-population /openapi.json get /v1/populations/{populationTagId} Read an existing population, identified by its ID. ### Permissions - `api.libraries.read` - `api.engagements.read` - `api.analyses.read` # Update Population Source: https://developer.mindbridge.ai/api-reference/populations/update-population /openapi.json put /v1/populations/{populationTagId} Update an existing population, identified by its ID. Engagement populations cannot be updated. ### Permissions - `api.libraries.write` - `api.analyses.write` # Create Reporting Period Configuration Source: https://developer.mindbridge.ai/api-reference/reporting-period-configuration/create-reporting-period-configuration /openapi.json post /v1/reporting-period-config Create a new reporting period configuration. ### Permissions - `api.reporting-period-config.write` # Delete Reporting Period Configuration Source: https://developer.mindbridge.ai/api-reference/reporting-period-configuration/delete-reporting-period-configuration /openapi.json delete /v1/reporting-period-config/{reportingPeriodConfigurationId} Delete an existing reporting period configuration, identified by its ID. ### Permissions - `api.reporting-period-config.delete` # Query Reporting Period Configuration Source: https://developer.mindbridge.ai/api-reference/reporting-period-configuration/query-reporting-period-configuration /openapi.json post /v1/reporting-period-config/query Query reporting period configurations, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` ### Permissions - `api.reporting-period-config.read` # Read Reporting Period Configuration Source: https://developer.mindbridge.ai/api-reference/reporting-period-configuration/read-reporting-period-configuration /openapi.json get /v1/reporting-period-config/{reportingPeriodConfigurationId} Read an existing reporting period configuration, identified by its ID. ### Permissions - `api.reporting-period-config.read` # Create Risk Range Source: https://developer.mindbridge.ai/api-reference/risk-ranges/create-risk-range /openapi.json post /v1/risk-ranges Create a new set of risk ranges. Risk ranges can be created at the library level, by setting an associated library ID. Risk ranges can be created at the engagement level by setting an engagement ID. You must set at least one of these IDs to successfully create a risk range. ### Permissions - `api.risk-ranges.write` # Delete Risk Range Source: https://developer.mindbridge.ai/api-reference/risk-ranges/delete-risk-range /openapi.json delete /v1/risk-ranges/{riskRangesId} Delete an existing set of risk ranges. ### Permissions - `api.risk-ranges.delete` # Query Risk Range Source: https://developer.mindbridge.ai/api-reference/risk-ranges/query-risk-range /openapi.json post /v1/risk-ranges/query Query risk ranges with an optional filter. ### Queryable Fields - `id` - `OBJECT_ID` - `system` - `BOOLEAN` - `engagementId` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `libraryId` - `OBJECT_ID` ### Permissions - `api.risk-ranges.read` # Read Risk Range Source: https://developer.mindbridge.ai/api-reference/risk-ranges/read-risk-range /openapi.json get /v1/risk-ranges/{riskRangesId} Retrieve an existing set of risk ranges by its ID. ### Permissions - `api.risk-ranges.read` # Update Risk Range Source: https://developer.mindbridge.ai/api-reference/risk-ranges/update-risk-range /openapi.json put /v1/risk-ranges/{riskRangesId} Update an existing set of risk ranges by its ID. ### Permissions - `api.risk-ranges.write` # Create Risk Segmentation Config Source: https://developer.mindbridge.ai/api-reference/risk-segmentation-configs/create-risk-segmentation-config /openapi.json post /v1/risk-segmentation-configs Create a risk segmentation config for an analysis. The analysis must exist. The config `name` must not already be in use for that analysis. `segments` must include `risk_score`. See the tag description for how to choose `segments`, `columns`, `riskScoreIds`, and `riskGroups`, and for a full create example. # Delete Risk Segmentation Config Source: https://developer.mindbridge.ai/api-reference/risk-segmentation-configs/delete-risk-segmentation-config /openapi.json delete /v1/risk-segmentation-configs/{riskSegmentationConfigId} Delete an existing risk segmentation for an analysis, identified by its ID. # Query Risk Segmentation Configs Source: https://developer.mindbridge.ai/api-reference/risk-segmentation-configs/query-risk-segmentation-configs /openapi.json post /v1/risk-segmentation-configs/query Query risk segmentation configs, optionally applying a filter. Filter by `analysisId` to list configs for a specific analysis run. See the tag description for field meanings. ### Queryable Fields - `id` - `OBJECT_ID` - `analysisId` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `enabled` - `BOOLEAN` # Read Risk Segmentation Config Source: https://developer.mindbridge.ai/api-reference/risk-segmentation-configs/read-risk-segmentation-config /openapi.json get /v1/risk-segmentation-configs/{riskSegmentationConfigId} Read an existing risk segmentation for an analysis, identified by its ID. # Create Saved Filter Source: https://developer.mindbridge.ai/api-reference/saved-filters/create-saved-filter /openapi.json post /v1/saved-filters Create a saved filter. ### Permissions - `api.filters.write` # Delete Saved Filter Source: https://developer.mindbridge.ai/api-reference/saved-filters/delete-saved-filter /openapi.json delete /v1/saved-filters/{filterId} Delete a saved filter, identified by its ID. ### Permissions - `api.filters.delete` # Query Saved Filters Source: https://developer.mindbridge.ai/api-reference/saved-filters/query-saved-filters /openapi.json post /v1/saved-filters/query Query saved filters, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `organizationId` - `OBJECT_ID` - `libraryId` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` ### Permissions - `api.filters.read` # Read Saved Filter Source: https://developer.mindbridge.ai/api-reference/saved-filters/read-saved-filter /openapi.json get /v1/saved-filters/{filterId} Read a saved filter, identified by its ID. # Update Saved Filter Source: https://developer.mindbridge.ai/api-reference/saved-filters/update-saved-filter /openapi.json put /v1/saved-filters/{filterId} Update a saved filter, identified by its ID. ### Permissions - `api.filters.write` # Validate Saved Filter Source: https://developer.mindbridge.ai/api-reference/saved-filters/validate-saved-filter /openapi.json post /v1/saved-filters/validate Validate a saved filter for correctness against the provided data table ID, returning a list of actionable errors describing incompatibilities between the provided filter and table, if any. Additionally mismatches between display values in the provided filter and the target data table are returned as actionable errors with `severity` set to `WARNING`, which represent display values that are different that those in the target data table. ### Permissions - `api.filters.read` # Query Task History Source: https://developer.mindbridge.ai/api-reference/task-history/query-task-history /openapi.json post /v1/task-histories/query Query task histories, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `taskId` - `OBJECT_ID` ### Required Query Restrictions When querying for task history, a `taskId` field and either an `$eq` or `$in` term must be included. Queries without these restrictions will fail. ### Permissions - `api.tasks.read` # Read Task History Source: https://developer.mindbridge.ai/api-reference/task-history/read-task-history /openapi.json get /v1/task-histories/{taskHistoryId} Read an existing task history, identified by its ID. ### Permissions - `api.tasks.read` # Add Task Comment Source: https://developer.mindbridge.ai/api-reference/tasks/add-task-comment /openapi.json post /v1/tasks/{taskId}/add-comment Add a comment to a task. ### Permissions - `api.tasks.write` # Create Task Source: https://developer.mindbridge.ai/api-reference/tasks/create-task /openapi.json post /v1/tasks Create a new task. Tasks are created on entries or transactions based on their transaction type, and row ID or transaction ID fields. The analysis type determines which transaction types are permitted to create new tasks: For general ledger (for-profit), general ledger (not-for-profit), and general ledger (not-for-profit with funds) analyses: - `ENTRY` - `TRANSACTION` For accounts payable analyses: - `AP_ENTRY` - `AP_OUTSTANDING_ENTRY` For accounts receivable analyses: - `AR_ENTRY` - `AR_OUTSTANDING_ENTRY` The task type determines which of `rowId` and `transactionId` are required when creating a new task. The following table outlines which fields must be set for a given task type: | Type | `rowId` | `transactionId` | |------------------------|:-------:|:---------------:| | `ENTRY` | ✅ | ✅ | | `TRANSACTION` | ❌ | ✅ | | `AP_ENTRY` | ✅ | ❌ | | `AR_ENTRY` | ✅ | ❌ | | `AP_OUTSTANDING_ENTRY` | ✅ | ❌ | | `AR_OUTSTANDING_ENTRY` | ✅ | ❌ | All tasks created by this endpoint will have `sampleType` set to `MANUAL`. ### Permissions - `api.tasks.write` # Delete Task Source: https://developer.mindbridge.ai/api-reference/tasks/delete-task /openapi.json delete /v1/tasks/{taskId} Delete an existing task, identified by its ID. ### Permissions - `api.tasks.delete` # Query Task Source: https://developer.mindbridge.ai/api-reference/tasks/query-task /openapi.json post /v1/tasks/query Query tasks, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `engagementId` - `OBJECT_ID` - `analysisResultId` - `OBJECT_ID` - `analysisId` - `OBJECT_ID` - `analysisTypeId` - `OBJECT_ID` - `transaction` - `STRING` - `name` - `STRING` - `rowId` - `INT64` - `transactionId` - `INT64` - `status` - `STRING` - `assignedId` - `OBJECT_ID` - `auditAreas` - `ARRAY_STRINGS` - `assertions` - `ARRAY_STRINGS` - `type` - `STRING` - `sampleType` - `STRING` ### Permissions - `api.tasks.read` # Read Task Source: https://developer.mindbridge.ai/api-reference/tasks/read-task /openapi.json get /v1/tasks/{taskId} Read an existing task, identified by its ID. ### Permissions - `api.tasks.read` # Update Task Source: https://developer.mindbridge.ai/api-reference/tasks/update-task /openapi.json put /v1/tasks/{taskId} Update an existing task, identified by its ID. ### Permissions - `api.tasks.write` # Query Transaction Id Preview Source: https://developer.mindbridge.ai/api-reference/transaction-id-previews/query-transaction-id-preview /openapi.json post /v1/transaction-id-previews/query Query transaction ID previews, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `analysisSourceId` - `OBJECT_ID` ### Permissions - `api.analysis-sources.read` # Read Transaction Id Preview Source: https://developer.mindbridge.ai/api-reference/transaction-id-previews/read-transaction-id-preview /openapi.json get /v1/transaction-id-previews/{transactionIdPreviewId} Read an existing transaction ID preview, identified by its ID. ### Permissions - `api.analysis-sources.read` # Create User Source: https://developer.mindbridge.ai/api-reference/users/create-user /openapi.json post /v1/users Create a new user. When creating a user, you must provide the user’s email address and a user role. The email address must not be associated with an existing user. The following roles may not be created with the `Create User` endpoint: - `ROLE_MINDBRIDGE_SUPPORT` - `ROLE_CLIENT` Upon creation, an account activation email will be sent to the provided email address. ### Rate limit This endpoint is subject to a maximum limit of 100 requests per hour. Once the limit is exceeded, the `X-User-Hour-Limit-Remaining` response header will be set, and it’s value will indicate the number of seconds until the rate limit is reset. **Note:** This rate limit is shared with the `Update User` and `Resend activation email` endpoints. Once the limit is reached, subsequent calls to any of these endpoints will fail until the rate limit resets. ### Permissions - `api.users.write` # Delete User Source: https://developer.mindbridge.ai/api-reference/users/delete-user /openapi.json delete /v1/users/{userId} Delete an existing user, identified by its ID. Users with the following roles cannot be deleted: - `ROLE_ADMIN` - `ROLE_MINDBRIDGE_SUPPORT` - API Token Users with the `serviceAccount` property set to `true` ### Permissions - `api.users.delete` # Get Current User Source: https://developer.mindbridge.ai/api-reference/users/get-current-user /openapi.json get /v1/users/current Read the current user tied to the provided API token. This endpoint is not restricted by any permissions and can be used to test the API. # Query User Source: https://developer.mindbridge.ai/api-reference/users/query-user /openapi.json post /v1/users/query Query users, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `email` - `STRING` - `role` - `STRING` - `enabled` - `BOOLEAN` ### Permissions - `api.users.read` # Read User Source: https://developer.mindbridge.ai/api-reference/users/read-user /openapi.json get /v1/users/{userId} Read an existing user, identified by its ID. ### Permissions - `api.users.read` # Resend Activation Link Source: https://developer.mindbridge.ai/api-reference/users/resend-activation-link /openapi.json post /v1/users/{userId}/resend-activation-link Send a previously invited user a new activation email. Users who have `validated` equal to `true` or `enabled` equal to `false` cannot be sent activation emails. ### Rate limit This endpoint is subject to a maximum limit of 100 requests per hour. Once the limit is exceeded, the `X-User-Hour-Limit-Remaining` response header will be set, and it’s value will indicate the number of seconds until the rate limit is reset. **Note:** This rate limit is shared with the `Create User` and `Update User` endpoints. Once the limit is reached, subsequent calls to any of these endpoints will fail until the rate limit resets. ### Permissions - `api.users.write` # Update User Source: https://developer.mindbridge.ai/api-reference/users/update-user /openapi.json put /v1/users/{userId} Update an existing user, identified by their user ID. Only the `enabled` and `role` properties can be updated, with some exceptions. The `enabled` property cannot be changed for users with the following roles: - `ROLE_ADMIN` - `ROLE_MINDBRIDGE_SUPPORT` - API Token Users with the `serviceAccount` property set to `true` The `role` property cannot be changed for users with the following roles: - `ROLE_ADMIN` - `ROLE_CLIENT` - `ROLE_MINDBRIDGE_SUPPORT` - API Token Users with the `serviceAccount` property set to `true` ### Rate limit This endpoint is subject to a maximum limit of 100 requests per hour. Once the limit is exceeded, the `X-User-Hour-Limit-Remaining` response header will be set, and it’s value will indicate the number of seconds until the rate limit resets. **Note:** This rate limit is shared with the `Create User` and `Resend activation email` endpoints. Once the limit is reached, subsequent calls to any of these endpoints will fail until the rate limit resets. ### Permissions - `api.users.write` # Query Webhook Event Logs Source: https://developer.mindbridge.ai/api-reference/webhook-event-logs/query-webhook-event-logs /openapi.json post /v1/webhook-event-logs/query Query webhook event logs, optionally applying a filter. ### Queryable Fields - `status` - `STRING` - `webhookId` - `OBJECT_ID` - `attemptStartDate` - `DATE_TIME` - `eventType` - `STRING` - `responseStatusCode` - `INT32` ### Permissions - `api.webhooks.read` # Read Webhook Event Log Source: https://developer.mindbridge.ai/api-reference/webhook-event-logs/read-webhook-event-log /openapi.json get /v1/webhook-event-logs/{webhookEventId} Read an existing Webhook event log, identified by its ID. ### Permissions - `api.webhooks.read` # Create Webhook Source: https://developer.mindbridge.ai/api-reference/webhooks/create-webhook /openapi.json post /v1/webhooks Create a new webhook. ### Permissions - `api.webhooks.write` # Delete Webhook Source: https://developer.mindbridge.ai/api-reference/webhooks/delete-webhook /openapi.json delete /v1/webhooks/{webhookId} Delete an existing **Webhook**. ### Permissions - `api.webhooks.delete` # Query Webhooks Source: https://developer.mindbridge.ai/api-reference/webhooks/query-webhooks /openapi.json post /v1/webhooks/query Query webhooks, optionally applying a filter. ### Queryable Fields - `id` - `OBJECT_ID` - `name` - `STRING` - `url` - `STRING` - `events` - `LIST` ### Permissions - `api.webhooks.read` # Read Webhook Source: https://developer.mindbridge.ai/api-reference/webhooks/read-webhook /openapi.json get /v1/webhooks/{webhookId} Read an existing Webhook, identified by its ID. ### Permissions - `api.webhooks.read` # Update Webhook Source: https://developer.mindbridge.ai/api-reference/webhooks/update-webhook /openapi.json put /v1/webhooks/{webhookId} Update an existing webhook, identified by its ID. ### Permissions - `api.webhooks.write` # Welcome Source: https://developer.mindbridge.ai/dev-portal/introduction The MindBridge Developer Portal is your central hub for building, integrating, and extending the MindBridge platform. Whether you're automating workflows, integrating with external systems, or extracting analysis results, this is where you’ll find the resources to get started. We’re excited to support your integration journey and help you unlock the full power of MindBridge through automation and connectivity. MindBridge API SDKs Available Integrations # How to Connect Source: https://developer.mindbridge.ai/integrations/bi/power-bi/how-to-connect ## Step 1: Generate an API Token from MindBridge To authenticate with the API, you’ll need a Bearer token. How to generate it: 1. Log into your MindBridge tenant. 2. Navigate to Admin → API (Admins only). 3. Click Generate New Token. 4. Name it (e.g., “Power BI Integration”). 5. Copy the token — it won’t be visible again. Tokens can be revoked or rotated anytime from the same screen. ## Step 2: Create a Parameter in Power BI for the Token To securely reference the token in your queries: 1. Open Power BI Desktop. 2. Go to Transform Data → Manage Parameters → New Parameter. 3. Use the following values: * **Name:** apiToken * **Type:** Text * **Current Value:** Paste your token here — no “Bearer ” prefix ### Security Notes The token is stored in plain text within the `.pbix` file — limit access accordingly. For production or shared reports, publish to Power BI Service and configure a Gateway with securely stored credentials. For enterprise deployments, consider using Azure Key Vault integration to securely manage secrets (Power BI Premium feature). ## Step 3: Create a Basic Test Query to Validate the Connection This lightweight test will confirm that Power BI can connect to the MindBridge API. 1. Go to Home → Transform Data. 2. In the Power Query Editor, click Advanced Editor. 3. Paste the following M code, but replace `yourcompany` in the URL with the subdomain of your own MindBridge tenant. ```m theme={null} let token = "Bearer " & apiToken, url = "https://yourcompany.mindbridge.ai/api/v1/engagements/query?page=0&size=1", response = Web.Contents(url, [ Headers = [ #"Authorization" = token, #"Content-Type" = "application/json" ], Content = Text.ToBinary("{}") ]), json = Json.Document(response) in json ``` You should see a JSON response — typically one item or an empty content array — confirming the connection works. ## Step 4: Set Authentication Method to Anonymous To ensure Power BI uses your token rather than prompting for login: 1. Go to File → Options and settings → Data source settings. 2. Select or add your API domain (e.g., `https://yourcompany.mindbridge.ai`). 3. Click Edit Permissions. 4. Set Authentication Method to Anonymous. 5. Click OK. # Overview Source: https://developer.mindbridge.ai/integrations/bi/power-bi/overview You can combine MindBridge data with internal systems (e.g., client portfolios, workflow apps, Power Automate) to build end-to-end audit or control monitoring dashboards. ## Use Cases ### Operational Tracking * See how many engagements are active. * View usage trends by month, business unit, or engagement type. * Monitor activity (e.g., recent runs or task follow-up). ### Risk & Results Reporting * Visualize results from risk-scored analyses (e.g., GL, TRA, PRA). * Create charts showing risk distribution, exceptions, or flagged entries. * Track findings and resolutions (where applicable). # Example Use Case Source: https://developer.mindbridge.ai/integrations/data/example-use-case A global technology company uses Databricks as its centralized data platform, updating it nightly with ERP and operational data. To streamline workflows, they prefer MindBridge to source data directly from Databricks, reducing the need for multiple systems to access operational environments. Using the MindBridge integration notebooks with Databricks, the company enables a fully automated, end-to-end financial analytics workflow: * **Data preparation and transformation**\ A scheduled Databricks job prepares ERP and operational data by applying reusable, predefined transformation logic. Cleaned and structured datasets are formatted to match MindBridge requirements and pushed directly into MindBridge via API. * **Automated analysis orchestration**\ The same Databricks Notebook automates MindBridge API calls to trigger new analyses as soon as data is ready. This orchestration ensures that every data refresh (e.g., nightly or weekly) results in timely, consistent financial analysis—without manual intervention. * **Frictionless insights delivery**\ With automated data delivery and analysis execution, business users can access the latest results in MindBridge as part of their daily workflows. No separate data pulls or manual uploads are required. * **Integrated risk intelligence**\ Risk scores and analysis results are programmatically retrieved via API back into Databricks. The company leverages MindBridge outputs to conduct deeper investigations and enrich internal dashboards—enabling continuous risk monitoring and integrated reporting alongside other business KPIs. # Overview Source: https://developer.mindbridge.ai/integrations/data/overview MindBridge has developed a set of set of notebooks to create a streamlined integration betweeen Databricks and MindBridge. The same data workflows can be adapted for other cloud data platforms like [Snowflake](https://snowflake.com) and [Microsoft Fabric](https://www.microsoft.com/en-us/microsoft-fabric). # Benefits * **Operational efficiency:** Streamlines operations and eliminates the need for custom scripts. * **Focused risk mitigation:** Enables finance teams to concentrate on reviewing and mitigating risks more effectively. * **Seamless workflow:** Maintains consistent workflows within the Databricks environment. # Key aspects of the integration * **Pre-configured Python notebooks:** Access reusable Python notebooks designed to run within Databricks for tasks such as sending data to MindBridge, triggering analyses, and querying results. * **Customization:** Easily customize these notebooks to meet specific needs, such as adjusting data frequency, integrating custom data sources, or modifying analysis parameters. * **Resources and tutorials:** Leverage supporting documentation to help your team quickly set up and customize the notebooks for your environment. | Name | Description | | - | - | | MindBridge\_E2E\_Integration\_Tutorial | Provides a how-to guide for setting up a MindBridge integration with Databricks, covering steps like setting up an Organization and Engagement, performing a General Ledger analysis, and extracting key information from analysis results. | | MindBridge\_Explore\_GL\_Table | Provides an example of querying from a Databricks database of General Ledger data to create a file that can be leveraged as input into any MindBridge analysis. | | MindBridge\_E2E\_Analysis\_Data\_Flow | Demonstrates a complete initial configuration of a MindBridge organization, engagement, and analysis. It includes uploading data from Databricks to MindBridge, executing an analysis, and generating a link to view results in MindBridge. | | MindBridge\_Update\_Data\_Run\_Existing\_Analysis | Illustrates the process of updating data (e.g., adding new transactional data) from Databricks and running an existing analysis in MindBridge without modifying the original configuration. This use case supports periodic analysis needs, allowing for refreshed data insights based on the latest data updates. | | MindBridge\_Results\_Integration\_Example | Showcases how to pull MindBridge results back into Databricks, enabling further analysis using downstream tools. This allows users to integrate MindBridge results into dashboards or reports for deeper insight and communication. | [Download](https://github.com/mindbridge-ai/mindbridge-databricks-notebooks) the preconfigured Python notebooks for Databricks from GitHub. Reach out to your Customer Success representative if you need assistance integrating MindBridge with your Databricks environment. We are happy to support you through the process. # Integrations Source: https://developer.mindbridge.ai/integrations/index

Databricks, Snowflake, Microsoft Fabric

Power BI

 # Data Processing and Retention Source: https://developer.mindbridge.ai/mcp/data-processing-and-retention * The MindBridge MCP server operates in the same geographical region as your MindBridge environment. * Data returned to your assistant is processed or stored according to that assistant’s configuration and provider terms, which may involve a different region. * On *standard contract terms*, MindBridge may retain anonymized tool call inputs for 30 days, such as analysis identifiers, keyword searches, and SQL queries generated by the assistant. It does not log the analysis result rows returned to the assistant. * If your organization has contracted out of *section 5.2* of the *standard terms*, MindBridge logs the names of tools called but does not log their inputs. MindBridge does not control the assistant provider’s retention, processing locations, or subprocessors. Do not treat MindBridge logging as a complete record of what an assistant retrieved, stored, or shared. MindBridge’s existing *subscriber content terms* continue to apply. For customers on *standard contract terms*, MindBridge may retain tool call inputs in anonymized form for 30 days for maintenance and product improvement, with storage and processing in the same region as the customer’s MindBridge environment. These inputs include analysis identifiers, keyword searches, and SQL queries generated by the assistant. For customers who have contracted out of *section 5.2* of the *standard terms*, MindBridge logs the names of tools called but does not log their inputs. Consult your organization’s agreement for the terms that apply to you. These MindBridge practices are separate from the external AI provider’s handling of retrieved data. # Explore an Analysis Source: https://developer.mindbridge.ai/mcp/explore-an-analysis The assistant can: * Find analyses you can access. The recent-analysis list returns up to 50 analyses. Ask the assistant to search by name or keyword if the analysis you need is not in that list. * Describe the tables, fields, and risk scores available in a selected analysis. * Explain how control points score records. * Query result rows or aggregates when you granted analysis result data access. The connection cannot create, change, or delete MindBridge records, ingest data, run analyses, or perform Insights workflows. Continue to use MindBridge for those activities. Answers depend on the data in the selected analysis and the permissions you granted. Wording and layout vary by assistant and environment. Use the prompts below as a starting point, then confirm the analysis and results in MindBridge. ## Find and confirm the analysis Start by identifying the analysis you want to use. Include its name or other identifying details, and ask the assistant to confirm the analysis before retrieving results. For example: > Find recent general ledger analyses I can access. Show their names so I can choose one. ## Inspect the available data Then ask about the selected analysis: > What tables, fields, and risk scores are available in this analysis? > Explain how this control point scores records. ## Request specific results Once you understand the available data, request specific results. Specify the analysis, relevant fields, filters, threshold, and number of results you need: > Show the 20 highest-risk records in this analysis. Identify the risk score used to rank them and include the available record identifiers. > Count the records above this risk-score threshold and state the filters used. Ask the assistant to distinguish information retrieved from MindBridge from its own interpretation. Before you rely on a result, see [Security, Privacy, and Responsible Use](/mcp/security-privacy-and-responsible-use). # Get Started Source: https://developer.mindbridge.ai/mcp/get-started Connect a compatible AI assistant to MindBridge so you can explore completed analyses with plain-language questions. ## Before you begin You need: * A MindBridge account with access to the completed analyses you want to explore. If you cannot see an analysis in MindBridge, MCP cannot see it either. * MCP enabled by MindBridge for your environment (also called your tenant). MCP is not enabled by default. If it is not enabled, contact your MindBridge account team. * A compatible AI assistant that supports remote MCP connections and OAuth sign-in. MindBridge has tested this MCP with common LLM providers such as **ChatGPT**, **Claude**, **Cursor**, and **Microsoft Copilot Studio**. Other assistants that support a remote MCP server URL and OAuth may also work. Menu names may differ by product. * Your organization’s approval to use that assistant with the MindBridge data you intend to access. Each user authorizes their own connection. Sign-in uses OAuth 2.1; you do not need API keys, service accounts, or shared credentials. Read-only access does not mean the assistant cannot copy data. See [Security, Privacy, and Responsible Use](/mcp/security-privacy-and-responsible-use). For retention and regional processing, see [Data Processing and Retention](/mcp/data-processing-and-retention). ## MindBridge MCP Settings Page You must be a MindBridge administrator to view **Settings → MCP**. On that page you can: * Copy the **MCP server URL** for your environment. Each environment has its own URL. Connecting to the wrong URL queries that environment’s analyses. * See **connected applications** you have authorized. * **Revoke** access for an application you no longer need. See [Manage or Revoke Access](/mcp/manage-or-revoke-access). If you are not an administrator, ask one for the MCP server URL for your environment. If you are an administrator and the page is still unavailable, contact your MindBridge account team to confirm that MCP is enabled. ## Connect your AI assistant 1. Sign in to **MindBridge** as an administrator and open **Settings → MCP**. 2. Copy the MCP server URL for your MindBridge environment. Copy the MCP server URL for your environment. 3. In ChatGPT, Claude, Cursor, Microsoft Copilot, or another compatible assistant, open MCP or connector settings and add the copied URL. 4. Sign in to MindBridge when prompted, using your normal sign-in process and your organization’s existing identity controls. 5. Review the MindBridge consent screen and approve the permissions needed for your task. To use all available capabilities, grant both analysis metadata access and analysis result data access, described below. Adding the MindBridge MCP server in Claude. After you connect, start with [Explore an Analysis](/mcp/explore-an-analysis). ## Access and permissions Every request runs with your MindBridge user permissions. The assistant can access only the analyses available to you in MindBridge. Removing or restricting your access in MindBridge also affects your MCP connection. The consent screen requests access through two read-only permissions: * **Analysis metadata (`api.analyses.read`):** Find analyses, describe their structure, and explain control points. * **Analysis result data (`api.data-tables.read`):** Query specific result rows or aggregates. If you grant only metadata access, the assistant can explore analysis structure but cannot retrieve underlying result rows. There is no write permission available for this connection. # Overview Source: https://developer.mindbridge.ai/mcp/introduction Model Context Protocol (MCP) is an open standard that connects AI assistants to external data and tools. MindBridge’s MCP connection lets you explore completed MindBridge analyses from a compatible AI assistant, using plain-language questions to find analyses, understand risk scoring, and retrieve specific results. The assistant queries results directly from your MindBridge environment, so you can explore them without first exporting data or copying analysis identifiers. You do not need to write SQL to ask questions. The connection provides **read-only access**. It cannot create, change, or delete MindBridge records, ingest data, run analyses, or perform Insights workflows. Continue to use MindBridge for those activities. Confirm prerequisites and connect AI assistants. Ask the assistant to find analyses and retrieve specific results. Set who can use MCP and revoke connections you no longer need. Understand the risks of retrieving analysis data through an assistant. Resolve common connection and retrieval issues. # Manage or Revoke Access Source: https://developer.mindbridge.ai/mcp/manage-or-revoke-access You must have the Admin role, and MCP must be enabled for your environment, to open **Admin → MCP**. Use that page to turn MCP on or off, set default scopes, add user overrides, and revoke active grants. ## MCP access **MCP access** is the master switch for the tenant. MCP access on and off settings on Admin → MCP * **On:** Users can connect agents if allowed by your scope settings below. * **Off:** No new connections are allowed, and all existing connections are revoked within a few minutes. ## Default scopes and user overrides **Default scopes** set the maximum permissions users can approve for an MCP client. A user’s regular MindBridge permissions still apply in addition to the scopes they choose. Default scopes options and user overrides on Admin → MCP Choose one default: * **Allow all scopes by default:** All users can use MCP within their normal MindBridge permission bounds. * **No MCP access by default:** No users can use MCP unless you add an override. Use this for testing MCP with a subset of your users. * **Allow specific scopes by default:** Limit the maximum scopes users can approve. For example, allow analysis metadata without analysis result data (row access). **User overrides** are exceptions to that default. You can grant a named user all scopes, a subset of scopes, or no MCP access. Select **Add user** to choose the person. Overrides are ignored if **MCP access** is set to **Off**. For a cautious rollout, turn **MCP access** on, set **No MCP access by default**, then add user overrides for the people who should connect. ## Active grants **Active grants** lists each current connection: user, application domain, application name, scopes, and last used. Search the list by user or application. To stop further MCP access through an application, revoke that grant. Revoking an active MCP grant on Admin → MCP Revoke a grant when someone stops using that assistant, leaves a role that should not have this access, or you notice unexpected sharing or tool behavior. Revoking a grant stops further MCP access through that application. It does not change the user’s ability to open analyses in MindBridge, and it does not delete information already retrieved by the assistant. Manage retained conversations, generated files, and other copies through the AI provider’s controls and your organization’s procedures. If you notice unexpected access, sharing, or tool behavior, stop the workflow, revoke the grant, and contact your administrator or security team. When a user is disabled in MindBridge, their connected agents automatically lose access within a few minutes. ## Save settings Select **Save settings** after you change **MCP access**, default scopes, or user overrides. Changing a radio button without saving does not apply the policy. Saving a tighter policy updates existing grants and removes scopes that are no longer allowed. Review the saved policy for your environment rather than assuming a default. # Security, Privacy, and Responsible Use Source: https://developer.mindbridge.ai/mcp/security-privacy-and-responsible-use MCP gives a compatible AI assistant read-only access to completed analyses the signed-in user can already see in MindBridge. The main risk is not that the assistant can change MindBridge records. It is that analysis data can leave your MindBridge environment and then be processed, stored, or shared in ways MindBridge does not control. Use of MCP remains subject to your organization’s applicable agreement with MindBridge, including the Terms of Use and related service documentation. By enabling MCP access, you acknowledge that you have reviewed the considerations described on this page and are authorized by your organization to enable the connection. Use this page for a security or acceptable-use review. Connection steps are in [Get Started](/mcp/get-started). Retention and regional processing are in [Data Processing and Retention](/mcp/data-processing-and-retention). ## Data can leave your MindBridge environment The assistant queries results directly from your environment. Retrieved data may include sensitive transaction, vendor, employee, customer, or journal information, depending on the analysis. After that data is returned, it is handled according to the assistant provider’s terms. That can include a different region, different retention, model training, or subprocessors. MindBridge’s data protections do not automatically extend to the external assistant. MindBridge does not operate or control third-party AI assistants. Before you allow a connection, ensure that the provider’s data retention, model training, processing locations, and sharing practices meet your organization’s requirements. Your organization’s approval to use an assistant is separate from the consent an individual grants when they connect. ## Access is read-only in MindBridge, not elsewhere The connection cannot create, change, or delete MindBridge records, ingest data, run analyses, or perform Insights workflows. There is no write permission for this connection. Read-only access still allows the assistant to retrieve and reproduce data. If the same assistant can send email, create documents, or publish content, it may share retrieved information through those tools. Review the assistant’s other connections and do not pair MCP with tools that send or publish automatically unless your organization has approved that combination. Analysis field values are source data, not instructions. A transaction description or other retrieved text can contain wording that tries to redirect the assistant, for example by asking it to send data elsewhere. Treat that text as data. Do not treat it as permission to act. ## Who can connect, and what they can see MCP is not enabled by default. An App Admin must enable the global toggle on the settings screen. Each user then authorizes their own connection with OAuth 2.1, using their normal sign-in and your organization’s existing identity controls. You do not need API keys, service accounts, or shared credentials. Every request runs with that user’s MindBridge permissions. The assistant can access only the analyses available to that user. Restricting or removing their MindBridge access also restricts the connection. Users choose which read-only permissions to grant: * **Analysis metadata** to find analyses, describe their structure, and explain control points. * **Analysis result data** to query specific result rows or aggregates. Granting only metadata access limits the assistant to structure and explanations. It cannot retrieve underlying result rows. ## What MindBridge logs, and what it does not delete MindBridge logging of MCP use is limited and depends on your contract. For customers on *standard terms*, MindBridge may retain anonymized tool call inputs for 30 days, such as analysis identifiers, keyword searches, and SQL generated by the assistant. If your organization has contracted out of *section 5.2* of the *standard terms*, MindBridge logs tool names but not their inputs. See [Data Processing and Retention](/mcp/data-processing-and-retention). Do not assume MindBridge logging is a complete record of what an assistant retrieved, stored, or shared. Copies in conversations, generated files, and the provider’s systems are outside MindBridge. Revoking a connection in **Admin → MCP** stops further access through that application. It does not delete information already retrieved. Manage those copies through the AI provider’s controls and your organization’s procedures. See [Manage or Revoke Access](/mcp/manage-or-revoke-access). ## Answers can be wrong or incomplete An assistant may misinterpret a field, apply an incorrect filter, summarize only part of an analysis or generate conclusions that are not fully supported by the underlying analysis results. Before relying on an answer: * Confirm that it used the intended analysis, risk score, and filters. * Check whether the result is a limited list or represents all relevant records. * Verify important figures and explanations against the analysis in MindBridge. * Review generated content before sharing it or using it in reports or audit documentation. A high-risk score alone is not evidence of fraud, error or non-compliance. Use MindBridge results alongside the analysis context and your professional judgment. MindBridge is responsible for operating the MCP Server and enforcing access controls within MindBridge. Customers are responsible for selecting and governing their AI assistant and reviewing AI-generated responses for their intended use. # Troubleshooting Source: https://developer.mindbridge.ai/mcp/troubleshooting ## FAQs ### I cannot find MCP settings. Contact your MindBridge administrator or account team to confirm availability. MindBridge must enable MCP for your environment before you can connect. ### My assistant cannot connect. Check that you used the URL copied from MindBridge, that the assistant supports remote MCP and OAuth, and that you completed sign-in and consent. ### I cannot find an analysis. Confirm that you can access it in MindBridge and that it has completed. Ask the assistant to search by name or keyword; the recent-analysis list returns up to 50 analyses. ### The assistant finds an analysis but cannot retrieve its result data. Check that you granted analysis result data access as well as analysis metadata access. If needed, reconnect and review the requested permissions. ### An answer appears incorrect or incomplete. Ask the assistant to identify its analysis, fields, filters, and result limits, then compare the answer with MindBridge. ## Get Help Your MindBridge account team can walk you through the connection, arrange a demonstration using your analyses, or provide more information for your organization’s security review. # Versioned notes Source: https://developer.mindbridge.ai/release-notes/versioned-notes # Release 26.09 ## v1.8.6 ### Risk segmentation configs Adds a new entity, risk segmentation config, which stores saved views for the Risk Segmentation dashboard on an analysis. Each config describes how results should be broken down (the segments), which summary columns appear in the table, and optional dashboard filters. Configs belong to one analysis. There is no update operation; to change a config, delete it and create a new one. * Adds a new `POST /risk-segmentation-configs` endpoint, which creates a new risk segmentation config. * Adds a new `GET /risk-segmentation-configs/{riskSegmentationConfigId}` endpoint, which returns a risk segmentation config identified by its ID. * Adds a new `POST /risk-segmentation-configs/query` endpoint, which queries risk segmentation configs based on a provided filter. * Adds a new `DELETE /risk-segmentation-configs/{riskSegmentationConfigId}` endpoint, which deletes a risk segmentation config identified by its ID. ### GDPdU unpack jobs Adds a new entity, GDPdU unpack job, which records asynchronous archive unpack operations and the File Manager files and directories they create. Unpack jobs are started from the File Manager transform endpoint and can be read or queried afterward. * Adds a new `POST /file-manager/transform/gdpdu-unpack` endpoint, which starts unpacking a GDPdU archive stored in File Manager and returns an async result whose target is the created GDPdU unpack job. * Adds a new `GET /gdpdu-unpack-jobs/{gdpduUnpackJobId}` endpoint, which returns a GDPdU unpack job identified by its ID. * Adds a new `POST /gdpdu-unpack-jobs/query` endpoint, which queries GDPdU unpack jobs based on a provided filter. ### Webhooks * Adds connection webhook events: `connection.created`, `connection.deleted`, `connection.data.complete`, and `connection.test.complete`. * Removes the `data.added` webhook event. Connection data transfer completion is now reported as `connection.data.complete`. * Adds MCP webhook events: `mcp.grant.approved`, `mcp.grant.denied`, `mcp.grant.revoked`, and `mcp.admin-settings.updated`. * The `mcp.admin-settings.updated` payload `userOverrides` field lists user IDs whose MCP override was added, changed, or removed. # Release 26.08 ## v1.8.5 ### Data flows Adds a new entity, data flow, which transforms data from a data catalog entry. The source catalog is identified by `inputDataCatalogEntryId`, and transformations are applied in order by the `operations` list. The first supported operation type is `REMAP`, which renames or duplicates columns. Data flows can be queried for data or used as a data catalog source. * Adds a new `POST /data-flows` endpoint, which creates a new data flow. * Adds a new `GET /data-flows/{dataFlowId}` endpoint, which returns a data flow identified by its ID. * Adds a new `PUT /data-flows/{dataFlowId}` endpoint, which updates a data flow identified by its ID. * Adds a new `POST /data-flows/query` endpoint, which queries data flows based on a provided filter. * Adds a new `DELETE /data-flows/{dataFlowId}` endpoint, which deletes a data flow identified by its ID. * Adds a new `POST /data-flows/{dataFlowId}/validate` endpoint, which validates a data query against a data flow, returning any validation errors. * Adds a new `POST /data-flows/{dataFlowId}/get-data` endpoint, which imports data from a data flow into a data table. ### Data catalog entry * Data catalog entries can now use a data flow as a source. These entries must set `source` to `DATA_FLOW` and provide a valid `dataFlowId`. Circular dependencies between data flows and catalogs are rejected. * Added `precision` and `scale` fields to data catalog entry columns. `precision` is returned on read; `scale` can be set on create and update. ### Connections * The Connection get-data endpoint now also requires the `api.data-tables.write` permission. * Added `precision` and `scale` fields to the Tabular Schema Column model. `precision` is returned on read; `scale` can be set on create. # Release 26.07 ## v1.8.5 ### Data catalog entry Adds a new entity, data catalog entry, which can be used to model remote and local data for use in MindBridge. Data can be imported from a remote or local source through a data catalog. Each import creates a Data Source Import Task entity that tracks the status of the import job. * Adds a new `POST /data-catalog-entries` endpoint, which creates a new data catalog entry. * Adds a new `GET /data-catalog-entries/{dataCatalogEntryId}` endpoint, which returns a data catalog entry identified by its ID. * Adds a new `PUT /data-catalog-entries/{dataCatalogEntryId}` endpoint, which updates a data catalog entry identified by its ID. * Adds a new `POST /data-catalog-entries/query` endpoint, which queries data catalog entries based on a provided filter. * Adds a new `DELETE /data-catalog-entries/{dataCatalogEntryId}` endpoint, which deletes a data catalog entry identified by its ID. * Adds a new `POST /data-catalog-entries/{dataCatalogEntryId}/validate` endpoint, which validates a data catalog entry's source configuration, returning any validation errors. * Adds a new `POST /data-catalog-entries/{dataCatalogEntryId}/get-data` endpoint, which retrieves data from the data catalog entry's source. * Adds a new `GET /data-source-import-tasks/{dataSourceImportTaskId}` endpoint, which returns a data source import task identified by its ID. * Adds a new `POST /data-source-import-tasks/query` endpoint, which queries data source import tasks based on a provided filter. ### Connection data source The Connection Data Source entity and its endpoints have been removed and replaced by the Data Catalog feature. ### Data tables * The Query Data Table endpoint accepts a query string parameter, `include-unstable-schemas=true`, to allow querying unstable table schema. Unstable table schema may be removed or modified in future versions. * Added `apiStability` field to the data table entity, indicating whether a table's schema is stable or may change in future API versions. This field is queryable. * The Data Table Data endpoint maximum page size has been increased from 100 to 2000. ### Connections * The `name` field on the Connection entity is now queryable. * Added `sortProperties` field to the Connection get-data request, allowing callers to specify sort order when retrieving data. * Added `displayName` and `description` fields to the Tabular Schema and Tabular Schema Column models, providing richer metadata for connection table schemas. ### Analysis source * The Update Analysis Source endpoint now validates the workflow state before allowing updates. Updates are only permitted when the source is in one of the following states: `FORMAT_DETECTED`, `COLUMNS_ANALYZED`, `DATA_VALIDATION_CONFIRMED`, `EFFECTIVE_DATE_METRICS_ANALYZED`, `INTEGRITY_CHECKED`, `PARSED`, or `FUNDS_REVIEWED`. * The Update and Delete Analysis Source endpoints now reject requests when asynchronous jobs are in progress for the source. ### Async results * Added `DATA_SOURCE_IMPORT_TASK` as a new async result entity type, used to track data catalog import operations. ### Webhooks * Simplified webhook URL restrictions. URLs must use HTTPS, use a fully qualified hostname, and must not use an IP address. # Release 26.05 ## v1.8.4 ### Engagements * Added `emailSubscriptions` field to Engagement. This field links subscriptions to users, and is required on update. ### Analysis Source * Added presetHeaderRowIndex to Analysis Source. This field enables explicit header row declaration, which enables the overriding the automatic header detection algorithm. ### Connections * Added `name` field to Connections. This required field provides a user-readable name for the external data source connection. ### Validation Strictness * Increased validation across multiple entities (Engagement, Analysis Source, File Manager, Filters): * String fields that accept values now require at least one non-blank character. * Array fields that accept collections now require at least one element. * Some existing payloads containing empty strings or empty arrays may now fail validation. # Release 26.03 ## v1.8.3 ### Admin reports * Adds new `POST /admin-reports/analysis-overview-report/run` endpoint – The Analysis overview report lists analyses and the associated risk score results. ### Connections Adds a new set of entities for managing external data source connections (such as Databricks), allowing users to connect to external databases, test connectivity, discover available tables, and retrieve data for use in MindBridge. * Adds a new `POST /connections` endpoint, which creates a new connection. * Adds a new `GET /connections/{connectionId}` endpoint, which returns a connection identified by its ID. * Adds a new `POST /connections/query` endpoint, which queries connections based on a provided filter. * Adds a new `DELETE /connections/{connectionId}` endpoint, which deletes a connection identified by its ID. * Adds a new `POST /connections/{connectionId}/test` endpoint, which tests connectivity for a connection. * Adds a new `POST /connections/{connectionId}/tables` endpoint, which discovers available tables from a connection. * Adds a new `POST /connections/{connectionId}/get-data` endpoint, which retrieves data from a specific table in a connection. ### Databricks Authorization Adds a new entity for managing Databricks connection credentials and authentication configuration. * Adds a new `POST /databricks-auth` endpoint, which creates a new Databricks authorization. * Adds a new `GET /databricks-auth/{authorizationId}` endpoint, which returns a Databricks authorization identified by its ID. * Adds a new `PUT /databricks-auth` endpoint, which updates a Databricks authorization. * Adds a new `DELETE /databricks-auth/{authorizationId}` endpoint, which deletes a Databricks authorization identified by its ID. * Adds a new `POST /databricks-auth/query` endpoint, which queries Databricks authorizations based on a provided filter. ### Connection Test Results Adds a new read-only entity for viewing the results of connection test operations. * Adds a new `GET /connection-test-results/{connectionTestResultId}` endpoint, which returns a connection test result identified by its ID. * Adds a new `POST /connection-test-results/query` endpoint, which queries connection test results based on a provided filter. ### Connection Tables Results Adds a new read-only entity for viewing the results of table discovery operations on connections. * Adds a new `GET /connection-tables-results/{connectionTablesResultId}` endpoint, which returns a connection tables result identified by its ID. * Adds a new `POST /connection-tables-results/query` endpoint, which queries connection tables results based on a provided filter. ### Connection Tables Adds a new read-only entity for viewing individual tables discovered from a connection. * Adds a new `GET /connection-tables/{connectionTableId}` endpoint, which returns a connection table identified by its ID. * Adds a new `POST /connection-tables/query` endpoint, which queries connection tables based on a provided filter. ### Connection Data Sources Adds a new entity for registering specific tables from a connection for use in MindBridge. * Adds a new `POST /connection-data-source` endpoint, which creates a new connection data source. * Adds a new `GET /connection-data-source/{connectionDataSourceId}` endpoint, which returns a connection data source identified by its ID. * Adds a new `POST /connection-data-source/query` endpoint, which queries connection data sources based on a provided filter. * Adds a new `DELETE /connection-data-source/{connectionDataSourceId}` endpoint, which deletes a connection data source identified by its ID. * Adds a new `POST /connection-data-source/{connectionDataSourceId}/get-data` endpoint, which retrieves data from a connection data source. ### File Manager * Adds a new `POST /file-manager/import-from-data-table` endpoint, which creates a new file manager file by exporting data from a data table as a CSV file. # Release 25.11 ## v1.8.2 ### General validation Several changes were made to make validation more strict, and remove invalid or impossible combinations. * Many required fields now require at least one nonblank character or entry be submitted to be valid. * Many types cleaned up to only accept one type of value, instead of a large list of types. * Many fields restricted to be integers or strings as appropriate. * Discriminators added to better restrict types, instead of being overly permissive. * Defaults added to many types, especially when there is only one valid type, making it optional in those cases. ### Analysis * Optional `reportingPeriodConfigurationId` field added. If not included, the analysis inherits the reporting period configuration from the engagement. If the engagement has no custom configuration, the analysis uses a standard reporting period. ### Analysis source * New workflow states have been added: `SCANNING_TRANSACTION_COMBINATIONS`, `PARSING_ICEBERG`, `PREPARING_ICEBERG`. ### Data Tables * For data table exports larger than 2 million rows, sorting is disabled to improve performance. ### File manager * Adds new `POST /file-manager/create-from-chunked-file` endpoint, which completes a chunked file import, given by its ID in the message body, and creates a file manager file entity. * Deprecated `POST /file-manager/import-from-chunked-file/{chunked-file-id}`, due to using nonstandard path parameters. ### Filter group condition * Added required `conditions` property, listing the entries within the condition group. ### Libraries * Allow analysis types to be added or removed from in-use libraries ### Reporting periods * Adds new `POST /reporting-period-config endpoint`, which creates a reporting period configuration. * Adds new `GET /reporting-period-config endpoint`, which reads an existing reporting period template entity, identified by its ID. * Adds new `DELETE /reporting-period-config/{reportingPeriodConfigurationId}` endpoint to delete an existing configuration, identified by its ID. * Adds new `POST /reporting-period-config/query` endpoint, which queries existing configuration on id, type, name, or originalName. * Added `reportingPeriodConfigurationId` property to the Analysis and Engagement model. This can replace `accountingPeriod`, but one of the two are required. * `reporting-period-config` permissions added. ### Run activity report request * PROCEDURE\_INSTANCE added as item type. * Correctly report errors when required `start` and `end` fields are not present. ### Saved filters * Changes to types, restricting acceptable values, such as removing BETWEEN as a valid monetaryValueType for Filter Monetary Value Condition, but being the only valid type for Filter Monetary Range Condition. ### Webhooks * Added field `role` to the user.invited and user.role webhook payloads. * Adds webhook payload information for more types to the OpenAPI specification describing how to receive and authenticate webhook payloads sent by MindBridge. * Webhooks can no longer be EXPIRED. # Release 25.09 ## v1.8.1 ### Webhooks * Added eventId to the webhook payload, deprecated the usage of it within the data object. * Added tenantId to the webhook payload * Adds new analysis, engagement and user webhook events. ### Webhook event logs Adds a new entity, Webhook event logs, that provides a log of all the attempts to deliver webhooks to third party services. This includes in progress requests, as well as completed and failed requests. * Adds a new `GET /webhook-event-logs/{webhookEventLogId}` endpoint, which returns a webhook event log identified by its ID. * Adds a new `POST /webhook-event-logs/query` endpoint, which queries webhook event logs based on a provided filter. # Release 25.07 ## v1.8.0 ### Webhooks Adds a new set of endpoints for managing the Webhooks entity, which allows users to manage webhook configurations. * Adds a new `GET /webhooks/{webhookId}` endpoint, which returns a webhook identified by its ID. * Adds a new `POST /webhooks` endpoint, which creates a new webhook entity. * Adds a new `PUT /webhooks/{webhookId}` endpoint, which updates a webhook entity identified by its ID. * Adds a new `DELETE /webhooks/{webhookId}` endpoint, which deletes a webhook entity identified by its ID. * Adds a new `POST /webhooks/query` endpoint, which queries webhooks based on a provided filter. * Adds webhook payload information to the OpenAPI specification, and API Reference, describing how to receive and authenticate webhook payloads sent by MindBridge. ### File Infos Adds a new set of endpoints for the *File Info* entity, which allows users to view the metadata of files related to analysis sources and file manager files. * Adds a new `GET/file-info/{fileInfoId}` endpoint, which returns a file info identified by its id. * Adds a new `POST/file-info/query` endpoint, which queries file infos based on a provided filter. ### Analysis source Deprecates the existing `fileInfo` field on the analysis source, adding in links to file info and file manager fields. * Deprecates the `fileManagerFileId` and `fileInfo` fields of the analysis source entity, replacing them with the `fileInfoVersions` and `fileManagerFiles` fields. * Adds a new `fileInfoVersions` field to analysis source, which provides a map of the available file infos related to the analysis source. This replaces the fileInfo field. * Adds a new `fileManagerFiles` field to analysis source, which provides a map of the available file manager files related to the analysis source. This replaces the current `fileManagerFileId`, which only linked to the latest file manager file. ### File Manager Adds a new `fileInfoId` field, providing access to the related file info entity. * Adds a new field `fileInfoId` to the file manager file entity, identifying the associated file info. ### Transaction ID Preview Fixes some bugs with the Transaction ID Preview entity. * Deprecates the `engagementId` and `analysisId` fields. * Fixes an issue where the `analysisSourceId`, `columnSelection`, `type` and `smartSplitter` fields were not being set correctly. # Release 25.05 ## v1.7.0 ### Filters Adds a new entity, *Saved Filter*, which allows users to manage saved library, organization, engagement and private filters. * Adds a new `GET /saved-filters/{savedFilterId}` endpoint, which returns a saved filter identified by its ID. * Adds a new `POST /saved-filters` endpoint, which creates a new saved filter entity. * Adds a new `PUT /saved-filters/{savedFilterId}` endpoint, which updates a saved filter entity identified by its ID. * Adds a new `DELETE /saved-filters/{savedFilterId}` endpoint, which deletes a saved filter entity identified by its ID. * Adds a new `POST /saved-filters/query` endpoint, which queries saved filters based on a provided filter. * Adds a new `POST /saved-filters/validate` endpoint, which returns a list of errors and warnings if the saved filter cannot be applied to the specified data table. ### Populations Adds new functionality to the *Populations* entity, allowing users to create, update, and delete populations. * Adds a new `POST /populations` endpoint, which creates a new population entity. * Adds a new `PUT /populations/{populationId}` endpoint, which updates a population entity identified by its ID. * Adds a new `DELETE /populations/{populationId}` endpoint, which deletes a population entity identified by its ID. * The following fields have been added to the population entity: `analysisTypeId`, `condition`, `legacyFilterFormat`, `displayCurrencyCode` and `displayLocale`. ### Risk ranges Adds a new entity, *Risk Range*, which enables customizing the low, medium, and high risk thresholds for their related risk scores. * Adds a new `GET /risk-ranges/{riskRangeId}` endpoint, which returns a risk range identified by its ID. * Adds a new `POST /risk-ranges` endpoint, which creates a new risk range entity. * Adds a new `PUT /risk-ranges/{riskRangeId}` endpoint, which updates a risk range entity identified by its ID. * Adds a new `DELETE /risk-ranges/{riskRangeId}` endpoint, which deletes a risk range entity identified by its ID. * Adds a new `POST /risk-ranges/query` endpoint, which queries risk ranges based on a provided filter. ### Analysis type configuration Adds a new entity, *Analysis Type Configuration*, which can be used to configure analysis settings at the library, engagement, and analysis level. * Adds a new `GET /analysis-type-configuration/{analysisTypeConfigurationId}` endpoint, which returns an analysis type configuration identified by its ID. * Adds a new `PUT /analysis-type-configuration/{analysisTypeConfigurationId}` endpoint, which updates an analysis type configuration entity identified by its ID. * Adds a new `POST /analysis-type-configuration/query` endpoint, which queries analysis type configurations based on a provided filter. ### Engagement account groups Adds new endpoints allowing for the creation, updating, and deletion of engagement account groups. * Adds a new `POST /api/v1/engagement-account-groups` endpoint, which creates a new engagement account group. * Adds a new `PUT /api/v1/engagement-account-groups/{engagementAccountGroupId}` endpoint, which updates an engagement account groups. * Adds a new `DELETE /api/v1/engagement-account-groups/{engagementAccountGroupId}` endpoint, which deletes an engagement account group. * The field `hidden` can now be used as part of a query filter. ### Data tables Adds new fields to the data table column model: * `mindBridgeField` - The MindBridge Field name this column is mapped to. * `typeaheadDataTableId` - The ID of the typeahead table this column is related to. ### Engagements * Removes `subscribedUserIds` field. ### Libraries * Adds a new `riskRangeEditPermission` field, which informs if risk scores within this library can have their risk ranges adjusted. # Q1 Release 2025 ## v.1.6.1 ### Libraries The industry tags field (`industryTags`) has been removed from the library creation endpoint. ### Account groups The industry tags field (`industryTags`) has been removed from the account group update endpoint. # Q4 Release 2024 ## v1.6.0 ### Tasks Adds the following new fields to the Task model: * `taskApprovalStatus` - The approval status of the task. * `dueDate` - The due date of the task. * `approvalId` - The ID of the approval associated with the task. * `tags` - classification tags for the task. * `amounts` - dollar value amounts associated with the task. ### Task History Adds a new entity, *Task History*, to store the history of task changes. * Adds a new `GET /task-histories/{taskHistoryId}` endpoint, which returns a task history entity identified by its ID. * Adds a new `POST /task-histories/query` endpoint, which queries task histories results based on a given filter. ### Users * Adds a new field, `recentLogins`, which shows when and via which IP the account was last used. # Q3 Release 2024 ## v1.5.0 ### Analysis Results A new entity, *Analysis Result*, has been added. This entity is the new primary entity for storing analysis results (currently limited to `data tables` and `tasks`). Now, instead of being limited to viewing only the most recent analysis results, the results from multiple runs of a given analysis can be accessed. This enhancement allows for a comprehensive history of analysis runs, and improves tracking of changes over time. * Adds a new `GET /analysis-results/{analysisResultsId}` endpoint, which returns an analysis result entity identified by its ID. * Adds a new `POST /analysis-results/query` endpoint, which queries analysis results based on a given filter. ### Tasks * Adds a new field to tasks called `analysisResultId`, which is queryable. * Removes the requirement to include an `analysisId` term when querying tasks. ### Data Tables * Adds a new field to data tables called `analysisResultId`, which is queryable. * Removes the requirement to include an `analysisId` term when querying data tables. ### Account Mappings A new entity, *Account Mapping*, has been added. This entity represents mappings between the accounts in General Ledger and Chart of Accounts file types to MindBridge Account Classification (MAC) codes. These must be configured and validated before running General Ledger analyses. * Adds a new `GET /account-mapping/{accountMappingId}` endpoint, which returns an account mapping entity identified by its ID. * Adds a new `POST /account-mapping/query` endpoint, which queries account mappings based on a given filter. * Adds a new `PUT /account-mapping/{accountMappingId}` endpoint, which updates an account mapping entity identified by its ID. * Adds a new `POST /account-mapping/verify` endpoint, which verifies all account mappings within the given engagement. * Adds a new `POST /account-mapping/delete-unused` endpoint, which deletes all unused account mappings of a given engagement. ### Engagement Account Group A new entity, *Engagement Account Group*, has been added to provide access to the account groups within engagement account groupings. * Adds a new `GET /engagement-account-groups/{engagementAccountGroupId}` endpoint, which returns an engagement account group identified by its ID. * Adds a new `POST /engagement-account-groups/query` endpoint, which queries engagement account groups given a filter. ### JSON Tables A new entity, *JSON Table*, has been added, which provides the ability to import data from a JSON-based source. * Adds a new `GET /json-tables/{jsonTableId}` endpoint, which returns a JSON table entity identified by its ID. * Adds a new `POST /json-tables` endpoint, which allows for the creation of a new JSON table. * Adds a new `POST /json-tables/{jsonTableId}/append` endpoint, which allows data to be appended to an existing JSON table entry. * Adds a new `POST /file-manager/import-from-json-table` endpoint, which enables creating a new file manager file from the data imported to a JSON table entry. ### File Manager Data Transformation: Merge Files * Adds a new `POST /file-manager/transform/merge` endpoint, which merges data from various file sources and creates a consolidated file with the aggregated data. ### Other * Marked some fields on the Page entity as deprecated, to be removed in a future release. * Platform-level rate limits provide additional protection on a per-IP address basis, but are set high enough that they should not be encountered during regular use. If the HTTP status `429` is returned, requests can be retried after approximately 30 seconds. Refer to the *Rate Limits* section of the API reference document for more information. # Q2 Release 2024 ## v1.4.1 ### Libraries * Adds a new field to the Library model, `riskScoreAndGroupsSelectionPermission`. ### Data Tables * Adds a new field to the Data Table Column model, `originalName`. ## v1.4.0 ### Account Groupings and Account Groups Two new entities, Account Groupings and Account Groups, have been added. These entities are used to map a set of accounts in a financial hierarchy to MindBridge Account Classification (MAC) codes for use in analyses and reports. * Adds new `GET /account-groupings/{accountGroupingId}` endpoint, which returns an account grouping identified by its ID. * Adds new `PUT /account-groupings/{accountGroupingId}` endpoint, which updates an account grouping identified by its ID. * Adds new `DELETE /account-groupings/{accountGroupingId}` endpoint, which deletes an account grouping identified by its ID. * Adds new `POST /account-groupings/query` endpoint, which queries account groupings given a filter. * Adds new `POST /account-groupings/export` endpoint, which exports an account grouping and all of its account groups within an Excel file. * Adds new `POST /account-groupings/import-from-chunked-file` endpoint, which creates a new account grouping and account groups based on a provided Excel file. * Adds new `POST /account-groupings/{accountGroupingId}/append-from-chunked-file` endpoint, which adds new account groups to an existing account grouping based on a provided Excel file. * Adds new `GET /account-groups/{accountGroupId}` endpoint, which returns an account group identified by its ID. * Adds new `POST /account-groups/query` endpoint, which queries account groups given a filter. * Adds new `PUT /account-groups/{accountGroupId}` endpoint, which updates an account group identified by its ID. ### Engagement Account Groupings A new entity, Engagement Account Grouping, has been added. This entity is the parent record to Engagement Account Groups, which are used to map accounts to MindBridge Account Classification (MAC) codes for use in analyses and reports in the context of an Engagement. * Adds new `GET /engagement-account-groupings/{engagementAccountGroupingId}` endpoint, which returns an engagement account grouping identified by its ID. * Adds new `POST /engagement-account-groupings/query` endpoint, which queries engagement account groupings given a filter. * Adds new `POST /engagement-account-groupings/export` endpoint, which exports an engagement account grouping and all of its account groups within an Excel file. # Q1 Release 2024 ## v1.3.1 ### Analysis Source Types * Adds new `mindbridgeFieldNameForNonMacGroupings` and `requiredForNonMacGroupings` fields to document exceptional cases where a MindBridge column name and required status may change dependent on if a MAC based account grouping is being used as part of an analysis. ## v1.3.0 ### Analysis Types A new entity, Analysis Type, has been added. This describes the features of an analysis, as well as the source types used as part of the analysis. This replaces the table of analysis types in the "Analysis" section of the API documentation. * Adds new `GET /analysis-types/{analysisTypeId}` endpoint, which returns an analysis type identified by its id. * Adds new `POST /analysis-types/query` endpoint, which queries analysis types given a filter. ### Analysis Source Types A new entity, Analysis Source Type, has been added. This describes the steps required when ingesting a source with this type, as well as the column mappings. This replaces the table of analysis source types in the "Analysis Source" section of the API documentation. * Adds new `GET /analysis-source-types/{analysisTypeId}` endpoint, which returns an analysis source type identified by its id. * Adds new `POST /analysis-source-types/query` endpoint, which queries analysis source types given a filter. ### Analysis * Adds new `POST /analyses/engagement-roll-forward` endpoint, which allows for the creation of a new analysis from an existing analysis that's part of another engagement. ### Libraries * Adds new `POST /libraries/` endpoint, which allows for the creation of a new library. * Adds new `PUT /libraries/{libraryId}` endpoint, which allows for the updating of a library. * Adds new `DELETE /libraries/{libraryId}` endpoint, which allows for the deletion of a library. * Adds new fields to the Library model, including `system` and `archived`, which are queryable. # Q3 Release 2023 ## v1.2.0 ### Analyses * Added `periodic` field, which indicates if an analysis is a periodic analysis. This can be set when creating a new analysis. * The values of `ApiAnalysisStatus`'s `preflightErrors` have changed with the addition of `periodic`. The `ready` field should be used to determine if an analysis can be run. ### Tasks * Using the `/query` endpoint now requires that an `analysisId` term be included. ### Data Tables * Using the `/query` endpoint now requires that an `analysisId` term be included. * Adds a new `type` field, which indicates the type of data table. It serves a similar purpose to the `logicalName` field, but is used in different contexts. # Get started Source: https://developer.mindbridge.ai/sdk/python/get-started The MindBridge Python SDK implements the official [Python API client library](https://pypi.org/project/mindbridge-api-python-client/) published on PyPI as `mindbridge-api-python-client`. Install the package using `pip`: ```bash theme={null} pip install mindbridge-api-python-client ``` For reliable environment management and to avoid dependency conflicts, use a Python virtual environment. You may use the standard library’s `venv` module or a third-party tool such as `uv`. # Authenticate and connect Generate an API token within your MindBridge tenant by following [Create an API token](/api-explorer/create-api-token). MindBridge recommends securely managing your API credentials. In these examples, environment variables are used: * `MINDBRIDGE_API_URL`: The full MindBridge tenant URL (for example, *\[subdomain]*.mindbridge.ai) * `MINDBRIDGE_API_TOKEN`: The API token generated for your account The following example connects to your MindBridge tenant and retrieves the authenticated user’s profile by calling the `/v1/users/current` endpoint: ```python theme={null} import os import mindbridgeapi as mbapi url = os.environ.get("MINDBRIDGE_API_URL", "") token = os.environ.get("MINDBRIDGE_API_TOKEN", "") server = mbapi.Server(url=url, token=token) user = server.users.get_current() print(f"Name: {user.first_name} {user.last_name}") print(f"Role: {user.role}") print(f"ID: {user.id}") ``` # Analyses Source: https://developer.mindbridge.ai/sdk/python/tutorials/analyses This section guides you through creating a general ledger analysis, creating a TRA vendor analysis, retrieving an analysis by its identifier, and querying analyses using the Python SDK. # Creating a general ledger analysis To set up an analysis, you first need to create or select an existing [organization](/sdk/python/tutorials/organizations) and [engagement](/sdk/python/tutorials/engagements). For details on how to work with these resources, see their respective guides. If you omit `library_id` from the `EngagementItem`, the MindBridge SDK creates a library using the `MindBridge for-profit (Mac v2) Library`. That library includes the general ledger, accounts payable, and accounts receivable analysis types by default. ```python theme={null} # get-or-create our organization organization_name = "Chapter 3 - Creating an Analysis" try: organization = next(server.organizations.get({"name": organization_name})) print(f"Organization '{organization_name}' already exists.") except StopIteration: new_organization_item = mbapi.OrganizationItem( name=organization_name, external_client_code="My Client ID", # Optional manager_user_ids=[user.id], # Optional ) organization_item = mbapi.OrganizationItem(name=organization_name) organization = server.organizations.create(organization_item) print(f"Organization '{organization_name}' created.") engagement_name = "Engagement - MindBridge for-profit Library" try: new_engagement_item = mbapi.EngagementItem( organization_id=organization.id, name=engagement_name, engagement_lead_id=user.id, ) engagement = server.engagements.create(new_engagement_item) print(f"Created the new engagement {engagement.name}") except mbapi.exceptions.ValidationError: engagement = next( server.engagements.get( {"organizationId": organization.id, "name": engagement_name} ) ) print( f"Fetched the engagement '{engagement.name}' from the organization with id " f"{organization.id}" ) ``` After the engagement **Engagement - MindBridge for-profit Library** exists, create an analysis within it. ```python theme={null} from datetime import date new_gl_analysis_item = mbapi.AnalysisItem( name="GL Analysis", engagement_id=engagement.id, currency_code="CAD", analysis_periods=[ mbapi.AnalysisPeriod(end_date=date(2024, 12, 31), start_date=date(2024, 1, 1)) ], analysis_type_id=mbapi.AnalysisTypeItem.GENERAL_LEDGER, ) analysis = server.analyses.create(new_gl_analysis_item) print( f"https://{os.getenv('MINDBRIDGE_URL')}/app/organization/{organization.id}/" f"engagement/{engagement.id}/analysis-list" ) ``` At the link printed above, an analysis is ready for data upload. # Creating a custom analysis To create a custom analysis, you first need a library with your desired analysis type. Then create an engagement that uses that library. In this example, you set up a TRA vendor analysis by creating an analysis type from the `TRA Vendor Template` that MindBridge provides. Create a TRA vendor analysis type in the Analysis Designer: 1. Open the Analysis Designer. 2. Find the analysis type named **TRA Vendor Template**. 3. Duplicate **TRA Vendor Template** and set the name to **SDK TRA Vendor**. 4. Click **Save**. 5. Return to the Analysis Designer page. 6. Select **Publish** on **SDK TRA Vendor**. Then create a library that includes that analysis type: 1. Open the Libraries page. 2. Select **Create Library**. 3. Set the name to **SDK TRA Vendor Library**. 4. Set the base library to **MindBridge for-profit (MAC v.2)**. 5. Add **SDK TRA Vendor** to the analysis types. 6. Set the account grouping to **Mac v.2**. 7. Select **Create Library**. You should now have a library named **SDK TRA Vendor Library** that contains the analysis type **SDK TRA Vendor**. Create an engagement that uses this library by setting `library_id` on the `EngagementItem`. ```python theme={null} all_libraries = server.libraries.get() vendor_library = next( library for library in all_libraries if library.name == "SDK TRA Vendor Library" ) organization_name = "Chapter 3 - Creating an Analysis" try: organization = next(server.organizations.get({"name": organization_name})) print(f"Organization '{organization_name}' already exists.") except StopIteration: new_organization_item = mbapi.OrganizationItem( name=organization_name, external_client_code="My Client ID", # Optional manager_user_ids=[user.id], # Optional ) organization_item = mbapi.OrganizationItem(name=organization_name) organization = server.organizations.create(organization_item) print(f"Organization '{organization_name}' created.") engagement_name = "Engagement - SDK TRA Vendor Library" try: new_engagement_item = mbapi.EngagementItem( organization_id=organization.id, name=engagement_name, engagement_lead_id=user.id, library_id=vendor_library.id, ) engagement = server.engagements.create(new_engagement_item) print(f"Created the new engagement '{engagement.name}'") except mbapi.exceptions.ValidationError: engagement = next( server.engagements.get( {"organizationId": organization.id, "name": engagement_name} ) ) print( f"Fetched the engagement '{engagement.name}' from the organization with id " f"{organization.id}" ) ``` After the engagement **Engagement - SDK TRA Vendor Library** exists, create an analysis within it. Fetch the analysis type from the engagement as shown below. ```python theme={null} from datetime import date all_libraries = server.libraries.get() vendor_library = next( library for library in all_libraries if library.name == "SDK TRA Vendor Library" ) available_analysis_types = list(vendor_library.analysis_types) print(f"These are the Analysis Types available in the library '{vendor_library.name}'") for at in available_analysis_types: print(at.name) tra_vendor_analysis_type = next( analysis_type for analysis_type in available_analysis_types if analysis_type.name == "SDK TRA Vendor" ) new_gl_analysis_item = mbapi.AnalysisItem( name="GL Analysis", engagement_id=engagement.id, currency_code="CAD", analysis_periods=[ mbapi.AnalysisPeriod(end_date=date(2024, 12, 31), start_date=date(2024, 1, 1)) ], analysis_type_id=tra_vendor_analysis_type.id, ) analysis = server.analyses.create(new_gl_analysis_item) print( f"https://{os.getenv('MINDBRIDGE_URL')}/app/organization/{organization.id}/" f"engagement/{engagement.id}/analysis-list" ) ``` # Engagements Source: https://developer.mindbridge.ai/sdk/python/tutorials/engagements An engagement represents a service or activity performed for one of your clients. When you create an engagement within an organization, it will always be associated with that organization. Engagements house the analyses you run within MindBridge, like the general ledger analysis. Because engagements belong to an organization, see [Organizations](/sdk/python/tutorials/organizations) for how to work with organizations using the Python SDK. ## Create a new engagement As in the web application, you can [create an engagement](https://support.mindbridge.ai/hc/en-us/articles/360055739694-Create-an-engagement) using the Python SDK. ```python theme={null} organization = server.organizations.get_by_id("6793acbf7bd84f04412b114e") # (1)! engagement = mbapi.EngagementItem( # (2)! name="The Engagement Name", organization_id=organization.id, engagement_lead_id=organization.created_user_info.id, ) engagement = server.engagements.create(engagement) print(f"{engagement.id=}\n{engagement.name=}") #> engagement.id='695fcdfa1bcebb393be82967' #> engagement.name='The Engagement Name' ``` 1. See [Organizations](/sdk/python/tutorials/organizations) for how to create the `server` and create an organization. 2. It is assumed you have imported the module with `import mindbridgeapi as mbapi`. ## Retrieving an engagement by ID You can retrieve an existing engagement by `id`. The example below uses the `id` of the engagement you created above. ```python theme={null} engagement = server.engagements.get_by_id("695fcdfa1bcebb393be82967") print(f"{engagement.id=}\n{engagement.name=}") #> engagement.id='695fcdfa1bcebb393be82967' #> engagement.name='The Engagement Name' ``` ## Querying engagements Query engagements, optionally applying a filter. Engagements can be searched using the MindBridge Query Language, as described in the MindBridge API Reference. The `get` function returns a [generator](https://docs.python.org/3/reference/expressions.html#generator-expressions), allowing you to iterate over search results or use the [`next()`](https://docs.python.org/3/library/functions.html#next) function. To list engagements for an existing organization, use the `engagements` property of the organization, which yields a generator of engagements within that organization. ```python theme={null} organization = server.organizations.get_by_id("6793acbf7bd84f04412b114e") try: engagement = next(organization.engagements) print(f"{engagement.id=}\n{engagement.name=}") except StopIteration: print("This organization has no engagements.") #> engagement.id='695fcdfa1bcebb393be82967' #> engagement.name='The Engagement Name' ``` # Organizations Source: https://developer.mindbridge.ai/sdk/python/tutorials/organizations **Organizations** represent each business/client/company/entity that you analyze with MindBridge. Organizations house all of your client’s engagements (audit/analysis), account mappings, and any other data imported into MindBridge for that client. See [Get Started](/sdk/python/get-started) for how to use the Python SDK with a `Server`. ## Create a new organization As in the web application, you can [create a new organization](https://support.mindbridge.ai/hc/en-us/articles/360057583033-Organization-management#01G66KHAB9Y1G7JKPK4PF6CD0C) using the Python SDK. ```python theme={null} organization = mbapi.OrganizationItem(name="The Organization Name") # (1)! organization = server.organizations.create(organization) # (2)! print(f"{organization.id=}\n{organization.name=}") #> organization.id='6793acbf7bd84f04412b114e' #> organization.name='The Organization Name' ``` 1. It is assumed you have imported the module with `import mindbridgeapi as mbapi`. 2. See [Get Started](/sdk/python/get-started) for how to create the `server`. The organization is now created in the web application, and the create action returns information about the created organization, including its `id`. ## Retrieving an organization by ID You can retrieve an existing organization by `id`. The example below uses the `id` of the organization you created above. ```python theme={null} organization = server.organizations.get_by_id("6793acbf7bd84f04412b114e") print(f"{organization.id=}\n{organization.name=}") #> organization.id='6793acbf7bd84f04412b114e' #> organization.name='The Organization Name' ``` ## Querying organizations Query organizations, optionally applying a filter. Organizations can be searched using the MindBridge Query Language, as described in the MindBridge API Reference. The `get` function returns a [generator](https://docs.python.org/3/reference/expressions.html#generator-expressions), allowing you to iterate over search results or use the [`next()`](https://docs.python.org/3/library/functions.html#next) function. ```python theme={null} try: organization = next(server.organizations.get({"name": "The Organization Name"})) print(f"{organization.id=}\n{organization.name=}") except StopIteration: print("No matching organization found.") ``` # Auto-Assign Tasks After Analysis Source: https://developer.mindbridge.ai/sdk/python/workflow-examples/task-assignment Learn how to use the Python SDK to export filtered rows from an analysis and automatically assign review tasks to designated users. This example demonstrates how to automatically assign review tasks using the [Python SDK](https://pypi.org/project/mindbridge-api-python-client/) after an analysis is completed. You will connect to an existing analysis, export a filtered set of rows from a data table, and assign entry tasks to appropriate MindBridge users based on values in your data, such as company code. ## Prerequisites Complete [Get started](/sdk/python/get-started) so the Python SDK is installed and configured. You also need: * A MindBridge analysis URL for an engagement that you can access. * The logical name of the data table you want to export, such as `gl_journal_lines`. ## Overview In this guide you will: * Parse an analysis URL to extract the MindBridge host and analysis result ID. * Authenticate with the MindBridge API and map business keys to user IDs by email for task assignment. * Export filtered rows to a CSV file, and create tasks only when no matching task exists (idempotent). ## Configure Your Inputs Adjust the values in the **Configure inputs** section at the top of the script below to match your analysis and task assignment requirements. Typically, you only need to update that section; the rest of the script follows a standard process. * **`analysis_url`**: The full MindBridge URL for the analysis. The script parses this to extract the server host and analysis result ID. You can also supply these values directly if your workflow provides them. * **`data_table_query`**: Filters applied to the data table to identify which rows should receive tasks (for example, by date range or minimum risk). Modify the fields and operators as needed. * **`data_table_logical_name`**: The logical name of the data table to export. This table must exist in the analysis. The script will print available logical names to help confirm your selection. * **`column_for_assigning`**: The column whose values determine the assignee, for example, `company_code`. You must provide a mapping for each expected value. * **`assigned_user_map`**: A mapping from values in `column_for_assigning` to MindBridge user email addresses. The script will look up each email and assign the task to the associated user. The listing below is one continuous script you can save and run. Step boundaries are marked with comments inside the code. ## Complete example ```python theme={null} import csv import os from datetime import date from pathlib import Path from tempfile import NamedTemporaryFile from urllib3.util import parse_url import mindbridgeapi as mbapi # --- Configure inputs (edit for your environment) --- # Replace with the full analysis URL from your browser. # Host and path IDs must match your tenant. analysis_url = ( "https://{your-tenant}.mindbridge.ai" "/app/organization/{ORG_ID}" "/engagement/{ENGAGEMENT_ID}" "/analysis/{ANALYSIS_RESULT_ID}" "/analyze/financial-statements" "?productCode=GENERAL_LEDGER" ) data_table_query = { "effective_date": { "$gte": date(2022, 4, 1), "$lt": date(2022, 6, 1), }, "risk": {"$gte": 15_00}, } data_table_logical_name = "gl_journal_lines" column_for_assigning = "company_code" # Keys must match values in your data column. # Values must be real user emails in your tenant. assigned_user_map = { "001": "reviewer-one@yourcompany.com", "002": "reviewer-two@yourcompany.com", } # --- Step 1: Parse the analysis URL --- parsed_url = parse_url(analysis_url) mindbridge_url = parsed_url.host parsed_url_path = parsed_url.path.split("/") analysis_idx = parsed_url_path.index("analysis") analysis_result_id = parsed_url_path[analysis_idx + 1] # --- Step 2: Connect, load analysis, resolve assignees --- # Load the API token, connect, fetch the analysis and # data tables, print logical names, restart data tables # for a fresh export, and resolve each assignee email # to a user ID. Errors if an email is missing or # ambiguous. token = os.environ.get("MINDBRIDGE_API_TOKEN", "") server = mbapi.Server(url=mindbridge_url, token=token) analysis_result = server.analysis_results.get_by_id( analysis_result_id ) analysis = server.analyses.get_by_id(analysis_result.analysis_id) print("Available data tables:") for data_table in analysis.data_tables: print( f"- logical_name: {data_table.logical_name} " f"(type: {data_table.type}, id: {data_table.id})" ) server.analyses.restart_data_tables(analysis) data_table = next( dt for dt in analysis.data_tables if dt.logical_name == data_table_logical_name ) print( f"Using logical_name: {data_table.logical_name} " f"(type: {data_table.type}, id: {data_table.id})" ) assigned_user_map_id = {} for key, assigned_user_email in assigned_user_map.items(): results = server.users.get(json={"email": assigned_user_email}) user, *others = results if not user: raise ValueError( f"User with email '{assigned_user_email}' " "not found." ) if others: raise Exception( f"Multiple users found with email " f"'{assigned_user_email}'. " "Please resolve duplicates." ) assigned_user_map_id[key] = user.id # --- Step 3: Export data and assign tasks --- # Export the selected table to CSV. For each row, create # an entry task for the mapped user unless a task already # exists for the same analysis, result, transaction, and # row (safe to rerun). with NamedTemporaryFile(delete=False) as temp_file: temp_file_path = Path(temp_file.name) print(f"Exporting to: {temp_file_path}") async_result = server.data_tables.export( data_table, fields=[ "rowid", "txid", "risk", "effective_date", column_for_assigning, ], query=data_table_query, ) server.data_tables.wait_for_export(async_result) temp_file_path = server.data_tables.download( async_result, output_file_path=temp_file_path ) with temp_file_path.open(newline="", encoding="utf_8") as infile: reader = csv.DictReader(infile) print("Assigning tasks for the following rows:") for row in reader: row_id = row["rowid"] transaction_id = row["txid"] print( f"- row_id: {row_id}, " f"transaction_id: {transaction_id}, " f"risk: {row['risk']}, " f"effective_date: {row['effective_date']}" ) assigned_id = assigned_user_map_id[row[column_for_assigning]] task = mbapi.TaskItem( row_id=row_id, transaction_id=transaction_id, type=mbapi.TaskType.ENTRY, status=mbapi.TaskStatus.OPEN, engagement_id=analysis.engagement_id, analysis_result_id=analysis_result.id, audit_areas=["Audit Area 1"], assigned_id=assigned_id, ) existing_task = next( server.tasks.get( json={ "analysisId": analysis.id, "analysisResultId": task.analysis_result_id, "transactionId": task.transaction_id, "rowId": task.row_id, } ), None, ) if existing_task: print( f" - Task already exists " f"(ID: {existing_task.id})" ) else: created_task = server.tasks.create(task) print(f" - Created task (ID: {created_task.id})") print("Task assignment complete.") temp_file_path.unlink() ``` *** When the script finishes, the filtered rows appear as tasks in MindBridge, assigned to the users specified in `assigned_user_map`. To modify this workflow, adjust the export `fields`, the `data_table_query`, or the `TaskItem` fields (such as audit areas or task type) to fit your organization's review process.