Creating Referrals

Using The Referral Field

Our API will only attempt to generate and return a referral url if it is a part of the request query sent to us. We have already seen in the previous walkthroughs that you can add and remove fields to the query based on what data you do or do not want to receive.

A query that will get a referral url in the response would look like this:

query ($addressInput: AddressInput!) {
  address(address: $addressInput) {
    products {
      homeSell {
        isEligible
        valueEstimate {
          lower
          upper
        }
        referral {
          # must include in order to get the actual url from the object
          url
        }
      }
    }
  }
}

This query will result in our API creating and including a referral url in the response to your application’s request. This referral url will not, however, be able to add tracking to your referral so that your application can receive status updates. We cover how to add the tracking id to the request in the next section.

Adding Referral Tracking

In order for us to know that you want to track this referral, and for us to reference the referrals when we send you status updates (via webhooks), you can optionally provide atrackingId parameter to the referral resolver.

Caution

The trackingId you provide us must be unique across all the different tracking id’s that your application has given us. It is your application’s responsibility to generate unique id’s.

To include a trackingId in the request, your query will need to add an input to the referral field:

query($addressInput: AddressInput!, $trackingId: String) {
  address(address: $addressInput) {
    products {
      homeSell {
        isEligible
        valueEstimate {
          lower
          upper
          }
        referral(trackingId: $trackingId) {
          url
        }
      }
    }
  }
}

Your query now expects a string input trackingId , which then gets passed as a parameter to the referral portion of the query. This is an important and useful aspect of GraphQL - different parts of the query tree can take in different inputs, which allows GraphQL API’s to support very complex queries. For more details on how that works checkout their docs.