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

# Engagement Create

> Creates a new engagement.

<RequestExample>
  ```graphql Request [expandable] theme={null}
  mutation EngagementCreate($input: EngagementCreateInput!) {
    engagementCreate(input: $input) {
      engagement {
        cancellable
        createdAt
        id
        owner
        shortId
        type
        clients {
          email
          firstName
          lastName
          middleName
          phoneNumber
        }
        ... on PurchaseEngagement {
          closingDate
          property {
            address {
              city
              country
              latitude
              longitude
              postalCode
              province
              shortTitle
              street
              title
              unitNumber
            }
          }
          status {
            state
          }
        }
        ... on RefinanceEngagement {
          closingDate
          property {
            address {
              city
              country
              latitude
              longitude
              postalCode
              province
              shortTitle
              street
              title
              unitNumber
            }
          }
          status {
            state
          }
        }
      }
      userErrors {
        code
        field
        message
      }
    }
  }
  ```

  ```graphql Variables theme={null}
  {
    "input": {
      "purchase": {
        "clients": [
          {
            "email": "jane@example.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "middleName": "M",
            "phoneNumber": "+14165551234"
          }
        ],
        "closingDate": "2025-06-15",
        "newMortgageFileIds": [
          "gid://ownright/FileRecord/1"
        ],
        "newMortgageNumber": "example-new-mortgage-number",
        "notes": "Additional notes here",
        "owner": "gid://ownright/TeamMember/1",
        "propertyAddress": {
          "city": "Toronto",
          "country": "CANADA",
          "postalCode": "M5V 1A1",
          "province": "ALBERTA",
          "street": "123 Main St",
          "unitNumber": "Suite 100"
        }
      }
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "engagementCreate": {
        "engagement": {
          "cancellable": true,
          "createdAt": "2025-01-15T10:30:00Z",
          "id": "gid://ownright/Engagement/1",
          "owner": "Jane Doe",
          "shortId": "ABC-123",
          "type": "PURCHASE",
          "clients": [
            {
              "email": "jane@example.com",
              "firstName": "Jane",
              "lastName": "Doe",
              "middleName": "M",
              "phoneNumber": "+14165551234"
            }
          ],
          "closingDate": "2025-06-15",
          "property": {
            "address": {
              "city": "Toronto",
              "country": "CANADA",
              "latitude": 1,
              "longitude": 1,
              "postalCode": "M5V 1A1",
              "province": "ALBERTA",
              "shortTitle": "123 Main St, Toronto",
              "street": "123 Main St",
              "title": "123 Main St, Toronto",
              "unitNumber": "Suite 100"
            }
          },
          "status": {
            "state": "CANCELLED"
          }
        },
        "userErrors": []
      }
    }
  }
  ```
</ResponseExample>

## Mutation field

`engagementCreate`

### Arguments

<ParamField path="input" type="EngagementCreateInput!" required>
  Input required to create an engagement.
  <Note>Exactly one of the following fields must be provided.</Note>

  <Expandable title="properties">
    <ParamField path="purchase" type="PurchaseEngagementCreateInput">
      Input to create a purchase engagement.

      <Expandable title="properties">
        <ParamField path="clients" type="[EngagementClientInput!]!" required>
          The clients for this engagement.
        </ParamField>

        <ParamField path="closingDate" type="ISO8601Date!" required>
          The closing date.
        </ParamField>

        <ParamField path="newMortgageFileIds" type="[FileRecordGID!]!" required>
          GIDs of staged file records for new mortgage files.
        </ParamField>

        <ParamField path="newMortgageNumber" type="String">
          The new mortgage number.
        </ParamField>

        <ParamField path="notes" type="String">
          Notes for the engagement.
        </ParamField>

        <ParamField path="owner" type="TeamMemberGID!" required>
          The team member who owns this engagement.
        </ParamField>

        <ParamField path="propertyAddress" type="AddressInput">
          The property address.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="refinance" type="RefinanceEngagementCreateInput">
      Input to create a refinance engagement.

      <Expandable title="properties">
        <ParamField path="clients" type="[EngagementClientInput!]!" required>
          The clients for this engagement.
        </ParamField>

        <ParamField path="closingDate" type="ISO8601Date!" required>
          The expected closing date.
        </ParamField>

        <ParamField path="newMortgageFileIds" type="[FileRecordGID!]!" required>
          GIDs of staged file records for new mortgage files.
        </ParamField>

        <ParamField path="newMortgageNumber" type="String">
          The new mortgage number.
        </ParamField>

        <ParamField path="notes" type="String">
          Notes for the engagement.
        </ParamField>

        <ParamField path="owner" type="TeamMemberGID!" required>
          The team member who owns this engagement.
        </ParamField>

        <ParamField path="propertyAddress" type="AddressInput">
          The property address.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Return fields

<ResponseField name="engagement" type="Engagement">
  The created engagement.

  <Expandable title="properties">
    <ResponseField name="cancellable" type="Boolean!" required>
      Whether the engagement can be cancelled.
    </ResponseField>

    <ResponseField name="clients" type="[EngagementClient!]!" required>
      The clients on this engagement.

      <Expandable title="properties">
        <ResponseField name="email" type="String">
          The email address of the client.
        </ResponseField>

        <ResponseField name="firstName" type="String">
          The first name of the client.
        </ResponseField>

        <ResponseField name="lastName" type="String">
          The last name of the client.
        </ResponseField>

        <ResponseField name="middleName" type="String">
          The middle name of the client.
        </ResponseField>

        <ResponseField name="phoneNumber" type="String">
          The phone number of the client.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="ISO8601DateTime!" required>
      The time the engagement was created.
    </ResponseField>

    <ResponseField name="id" type="EngagementGID!" required>
      The unique identifier of the engagement.
    </ResponseField>

    <ResponseField name="owner" type="String">
      The name of the engagement owner.
    </ResponseField>

    <ResponseField name="shortId" type="String!" required>
      A short human-readable identifier for the engagement.
    </ResponseField>

    <ResponseField name="type" type="EngagementType!" required>
      The type of the engagement.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="userErrors" type="[EngagementCreateUserError!]!" required>
  List of errors that occurred while executing the mutation.

  <Expandable title="properties">
    <ResponseField name="code" type="EngagementCreateUserErrorCode">
      Error code associated with the error.
    </ResponseField>

    <ResponseField name="field" type="[String!]">
      The path to the input field that caused the error.
    </ResponseField>

    <ResponseField name="message" type="String!" required>
      A description of the error.
    </ResponseField>
  </Expandable>
</ResponseField>

### Types

* [`AddressInput`](/lender-api/reference/members/inputs/address-input) (input) — Input for an address.
* [`Country`](/lender-api/reference/members/enums/country) (enum) — Possible countries.
* [`E164PhoneNumber`](/lender-api/reference/members/scalars/e164-phone-number) (scalar) — A valid phone number string in the E.164 format.
* [`Engagement`](/lender-api/reference/members/interfaces/engagement) (interface) — Represents an engagement.
* [`EngagementClient`](/lender-api/reference/members/objects/engagement-client) (object) — A client contact on an engagement.
* [`EngagementClientInput`](/lender-api/reference/members/inputs/engagement-client-input) (input) — Input for a client on an engagement.
* [`EngagementCreateInput`](/lender-api/reference/members/inputs/engagement-create-input) (input) — Input to create an engagement. Exactly one of the type-specific inputs must be provided.
* [`EngagementCreatePayload`](/lender-api/reference/members/objects/engagement-create-payload) (object) — Return type for the `engagementCreate` mutation.
* [`EngagementCreateUserError`](/lender-api/reference/members/objects/engagement-create-user-error) (object) — An error that could occur during the execution of the `engagementCreate` mutation.
* [`EngagementCreateUserErrorCode`](/lender-api/reference/members/enums/engagement-create-user-error-code) (enum) — Possible error codes that can be returned by EngagementCreateUserError.
* [`EngagementGID`](/lender-api/reference/members/scalars/engagement-gid) (scalar) — A global identifier for a Engagement object in format of 'gid://ownright/Engagement/ID'.
* [`EngagementType`](/lender-api/reference/members/enums/engagement-type) (enum) — The type of engagement.
* [`FileRecordGID`](/lender-api/reference/members/scalars/file-record-gid) (scalar) — A global identifier for a FileRecord object in format of 'gid://ownright/FileRecord/ID'.
* [`ISO8601Date`](/lender-api/reference/members/scalars/iso8601-date) (scalar) — An ISO 8601-encoded date
* [`ISO8601DateTime`](/lender-api/reference/members/scalars/iso8601-date-time) (scalar) — An ISO 8601-encoded datetime
* [`Province`](/lender-api/reference/members/enums/province) (enum) — Possible provinces.
* [`PurchaseEngagementCreateInput`](/lender-api/reference/members/inputs/purchase-engagement-create-input) (input) — Input to create a purchase engagement.
* [`RefinanceEngagementCreateInput`](/lender-api/reference/members/inputs/refinance-engagement-create-input) (input) — Input to create a refinance engagement.
* [`TeamMemberGID`](/lender-api/reference/members/scalars/team-member-gid) (scalar) — A global identifier for a TeamMember object in format of 'gid://ownright/TeamMember/ID'.