Skip to main content
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

1

Choose the engagement type

Decide whether you’re creating a purchase or refinance engagement. This determines which input field you’ll use:
Engagement typeInput fieldInput type
PurchasepurchasePurchaseEngagementCreateInput
RefinancerefinanceRefinanceEngagementCreateInput
Both input types share the same set of fields: clients, closingDate, owner, newMortgageFileIds, newMortgageNumber, notes, and propertyAddress.
2

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

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 {
          ... on PurchaseEngagementReceivedStatus {
            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.
4

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:
CodeDescription
INVALID_ENGAGEMENT_INPUTThe engagement input is invalid (e.g., missing required fields)
TEAM_MEMBER_NOT_FOUNDThe specified TeamMemberGID doesn’t exist in your organization
FILE_RECORD_NOT_FOUNDA FileRecordGID in newMortgageFileIds could not be found
FILE_RECORD_NOT_STAGEDA 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.