Creating an engagement

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

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.

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 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, then pass the resulting FileRecordGID values.

Construct and send the mutation

Here’s a complete example for creating a purchase engagement:

Request

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:

Variables

{
  "input": {
    "purchase": {
      "owner": "gid://ownright/TeamMember/1",
      "closingDate": "2025-09-15",
      "clients": [
        {
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "[email protected]",
          "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."
    }
  }
}

To create a refinance engagement instead, use the refinance key in the input with a RefinanceEngagementCreateInput. The fields are identical.

Handle the response

On success, the response includes the newly created engagement:

Successful response

{
  "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": "[email protected]"
          }
        ],
        "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:

Error response

{
  "data": {
    "engagementCreate": {
      "engagement": null,
      "userErrors": [
        {
          "code": "TEAM_MEMBER_NOT_FOUND",
          "field": ["input", "purchase", "owner"],
          "message": "The specified team member could not be found."
        }
      ]
    }
  }
}

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

Always fetch your team members first so you have valid TeamMemberGID values to assign as owners.
If you need to attach mortgage documents, complete the file upload flow before calling engagementCreate.
The newMortgageFileIds array can be empty if you don’t have documents to attach at creation time.
New engagements always start in the Received state.

Getting Started

Core Concepts

Guides

API Reference

Queries

Mutations

Members

Webhooks

Understanding `@oneOf`

Steps to create an engagement

Error codes

Tips

Next steps

Searching engagements

File uploads

​Understanding @oneOf

​Steps to create an engagement

​Error codes

​Tips

​Next steps

Searching engagements

File uploads

Understanding `@oneOf`

Steps to create an engagement

Error codes

Tips

Next steps