To create a referral, make a GraphQL mutation request to our API using one of the available referral create mutations (e.g. propertyClosingReferralCreate). This allows you to refer a client for a specific type of real estate transaction.

​
🛠️ Steps to create a referral

1

Choose a referral type and mutation

You’ll need to specify the type of referral you’d like to make. Once you know what kind of referral, choose to use the appropriate GraphQL mutation:

Referral typeMutationNotes
PurchasepropertyClosingReferralCreateSupply the PURCHASE_PROPERTY_CLOSING type.
SalepropertyClosingReferralCreateSupply the SALE_PROPERTY_CLOSING type.
RefinancerefinanceReferralCreate
Status Certificate ReviewstatusCertificateReviewCreate

Read our Partner API reference for all of the details on each mutation.

2

Construct the GraphQL mutation with all of the inputs

Once you know what type of referral you want to make, you need to construct the request with your desired inputs, for example:

Request
mutation PropertyClosingReferralCreate {
  propertyClosingReferralCreate(input: {
    type: PURCHASE_PROPERTY_CLOSING,
    contacts: [
      {
        firstName: "John",
        email: "[email protected]",
        primary: true
      }
    ],
    # ... other input
  }) {
    referral {
      id
    }
    userErrors {
      code
      message
    }
  }
}
3

Handle the response

On success, the response will include the newly created referral and any fields you have queried for. If something goes wrong, check the userErrors array for the error code and message (read more about errors in our Errors and response codes documentation)

✅ Example response

Successful response
{
  "data": {
    "propertyClosingReferralCreate": {
      "referral": {
        "id": "ref_12345"
      },
      "userErrors": []
    }
  }
}

❌ Error response

Error response
{
  "data": {
    "propertyClosingReferralCreate": {
      "referral": null,
      "userErrors": [
        {
          "code": "INVALID_EMAIL",
          "message": "Email must be a valid email address."
        }
      ]
    }
  }
}

​
🧠 Tips

  • Ensure the email is valid and unique for each contact.

  • You can include multiple contacts, but only one should be marked primary: true.