> ## Documentation Index
> Fetch the complete documentation index at: https://developer.mindbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

As engagements are within an organization, see [Organizations](/sdks/python/tutorials/organizations) for information on how to interact with organizations with the MindBridge API Python Client.

## Create a new engagement

Like the web app you can [Create an engagement](https://support.mindbridge.ai/hc/en-us/articles/360055739694-Create-an-engagement) using the MindBridge API Python Client.

<CodeGroup dropdown>
  ```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'
  ```
</CodeGroup>

1. See [Organizations](/sdks/python/tutorials/organizations) for how to create the `server` and create an organization
2. It's assumed you've imported the module with `import mindbridgeapi as mbapi`

## Retrieving an engagement by ID

You can retrieve an existing engagement, identified by its ID, as shown here using the ID of the organization created above.

<CodeGroup dropdown>
  ```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'
  ```
</CodeGroup>

## Querying engagements

Query engagements, optionally applying a filter. Engagements can be searched using the MindBridge Query Language, detailed 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.

If you want to get the engagements of an existing organization, the `engagement` property of the organization provides a generator of the engagements within that organization.

<CodeGroup dropdown>
  ```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'
  ```
</CodeGroup>