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

# Creating an engagement

> A step-by-step guide to submitting a new real estate file to Ownright

To create an engagement, use the `engagementCreate` mutation. This allows you to submit
a new real estate legal file to Ownright for either a purchase or refinance transaction.

## Understanding `@oneOf`

The `EngagementCreateInput` uses the `@oneOf` directive, which means you must provide
**exactly one** of the type-specific inputs:

* `purchase` — for a purchase engagement
* `refinance` — for a refinance engagement

You cannot supply both at the same time. This pattern ensures the engagement is created
with the correct type-specific fields.

## Steps to create an engagement

<Steps>
  <Step title="Choose the engagement type">
    Decide whether you're creating a **purchase** or **refinance** engagement. This
    determines which input field you'll use:

    | Engagement type | Input field | Input type                       |
    | --------------- | ----------- | -------------------------------- |
    | Purchase        | `purchase`  | `PurchaseEngagementCreateInput`  |
    | Refinance       | `refinance` | `RefinanceEngagementCreateInput` |

    Both input types share the same set of fields: `clients`, `closingDate`, `owner`,
    `newMortgageFileIds`, `newMortgageNumber`, `notes`, and `propertyAddress`.
  </Step>

  <Step title="Gather the required information">
    Before constructing the mutation, make sure you have:

    * **Owner** — A `TeamMemberGID` for the team member who will own this engagement.
      See [Lender and team members](/lender-api/core-concepts/lender-and-team-members)
      for how to fetch these.
    * **At least one client** — Each client needs a `firstName`, `lastName`, and `email`.
      Phone number and middle name are optional.
    * **Closing date** — The expected closing date in ISO 8601 format (e.g., `2025-09-15`).
    * **Mortgage files** (if any) — Upload documents first using the
      [staged file upload flow](/lender-api/guides/file-uploads), then pass the
      resulting `FileRecordGID` values.
  </Step>

  <Step title="Construct and send the mutation">
    Here's a complete example for creating a purchase engagement:

    ```graphql Request [expandable] theme={null}
    mutation CreatePurchaseEngagement($input: EngagementCreateInput!) {
      engagementCreate(input: $input) {
        engagement {
          ... on PurchaseEngagement {
            id
            shortId
            type
            closingDate
            owner
            clients {
              firstName
              lastName
              email
            }
            property {
              address {
                street
                city
                province
                postalCode
              }
            }
            status {
              state
            }
          }
        }
        userErrors {
          code
          field
          message
        }
      }
    }
    ```

    **Variables:**

    ```json Variables [expandable] theme={null}
    {
      "input": {
        "purchase": {
          "owner": "gid://ownright/TeamMember/1",
          "closingDate": "2025-09-15",
          "clients": [
            {
              "firstName": "Jane",
              "lastName": "Doe",
              "email": "jane.doe@example.com",
              "phoneNumber": "+14165551234"
            }
          ],
          "propertyAddress": {
            "street": "123 Main Street",
            "unitNumber": "Unit 4B",
            "city": "Toronto",
            "province": "ONTARIO",
            "postalCode": "M5V 2T6",
            "country": "CANADA"
          },
          "newMortgageNumber": "MTG-2025-001",
          "newMortgageFileIds": [],
          "notes": "Client prefers email communication."
        }
      }
    }
    ```

    <Note>
      To create a refinance engagement instead, use the `refinance` key in the input
      with a `RefinanceEngagementCreateInput`. The fields are identical.
    </Note>
  </Step>

  <Step title="Handle the response">
    On success, the response includes the newly created engagement:

    ```json Successful response [expandable] theme={null}
    {
      "data": {
        "engagementCreate": {
          "engagement": {
            "id": "gid://ownright/Engagement/42",
            "shortId": "ENG-42",
            "type": "PURCHASE",
            "closingDate": "2025-09-15",
            "owner": "Jane Smith",
            "clients": [
              {
                "firstName": "Jane",
                "lastName": "Doe",
                "email": "jane.doe@example.com"
              }
            ],
            "property": {
              "address": {
                "street": "123 Main Street",
                "city": "Toronto",
                "province": "ONTARIO",
                "postalCode": "M5V 2T6"
              }
            },
            "status": {
              "state": "RECEIVED"
            }
          },
          "userErrors": []
        }
      }
    }
    ```

    If something goes wrong, check the `userErrors` array:

    ```json Error response [expandable] theme={null}
    {
      "data": {
        "engagementCreate": {
          "engagement": null,
          "userErrors": [
            {
              "code": "TEAM_MEMBER_NOT_FOUND",
              "field": ["input", "purchase", "owner"],
              "message": "The specified team member could not be found."
            }
          ]
        }
      }
    }
    ```
  </Step>
</Steps>

## Error codes

The `engagementCreate` mutation can return the following error codes:

| Code                       | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| `INVALID_ENGAGEMENT_INPUT` | The engagement input is invalid (e.g., missing required fields)  |
| `TEAM_MEMBER_NOT_FOUND`    | The specified `TeamMemberGID` doesn't exist in your organization |
| `FILE_RECORD_NOT_FOUND`    | A `FileRecordGID` in `newMortgageFileIds` could not be found     |
| `FILE_RECORD_NOT_STAGED`   | A file record hasn't been uploaded yet via the staged upload URL |

## Tips

<ul>
  <li>
    Always fetch your team members first so you have valid `TeamMemberGID`
    values to assign as owners.
  </li>

  <li>
    If you need to attach mortgage documents, complete the [file upload
    flow](/lender-api/guides/file-uploads) before calling `engagementCreate`.
  </li>

  <li>
    The `newMortgageFileIds` array can be empty if you don't have documents to
    attach at creation time.
  </li>

  <li>New engagements always start in the **Received** state.</li>
</ul>

## Next steps

<CardGroup cols={2}>
  <Card title="Searching engagements" icon="magnifying-glass" href="/lender-api/guides/searching-engagements">
    Filter, sort, and paginate through your engagements.
  </Card>

  <Card title="File uploads" icon="upload" href="/lender-api/guides/file-uploads">
    Learn the staged upload flow for attaching mortgage documents.
  </Card>
</CardGroup>