API Overview

Our API is based on GraphQL and has a single endpoint. GraphQL APIs are organized in terms of types and fields and use types to ensure apps only ask for what’s possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.

API Pre-Release Mode

Our GraphQL API is currently evolving at a rapid pace to meet all of our platform's needs. You should expect frequent changes and growing capabilities at this time. We are not planning to provide production API access to lenders until Q2 2023 unless there is a compelling use case that cannot be solved with Sagas and Pushback Endpoints.

We will be releasing the API for direct use by our lenders in the near future, but for now we encourage our lenders to use our Sagas and pushback endpoints for most integration scenarios.

As we progress towards a public release of the API, there are a number of important changes we will be making that will impact any API integration:

• API Endpoint Splitting - we intend to split the GraphQL Api into two distinct endpoints:

  • Transactional API - intended for access by a borrower or lender agent,

  • Administration API - intended for access by a system administrator.

• Namespacing Mutations - we will be moving all of our mutations into a number of namespaces by topic to make it easier to navigate the mutations and find the appropriate mutation for a given use case.

• API Throttling - to protect our system resources, we will impose certain rate limits on API usage.

• Improved schema documentation

• Improved error codes / error messages - right now most errors have the same error code and it is difficult to determine the cause of the error without access to the Maxwell backend logs.

• Mutation return values - right now a lot of mutations return either true/false when they should really return the updated data according to GraphQL conventions.

• Improve subscriptions - unify GraphQL subscriptions for Saga completion and "events" into a single GraphQL subscription.

• Versioning - we will have a more formal versioning system and deprecation mechanism.

• Improve Pagination performance

About GraphQL

GraphQL is a query language for APIs and a runtime for fulfilling those queries with our existing data. GraphQL provides a complete and understandable description of the data in our API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Here is an example query defining exactly the data and its shape that you need from the server:

{
	partner(id: 1234) {
    sites {
      items {
        id
        name
        domain        
      }
    }
  }	
}

...and the response from the server in JSON format:

{
  "data": {
    "partner": {
      "sites": {
        "items": [
          {
            "id": "1",
            "name": "Hawkins Mortgage",
            "domain": "mortgage.hawkinsbank.com"
          },
          {
            "id": "2",
            "name": "Hawkins Credit Card Services",
            "domain": "credit.hawkinsbank.com"
          },
          {
            "id": "3",
            "name": "Hawkins Auto Finance",
            "domain": "auto.hawkinsbank.com"
          },
        ]
      }
    }
  }
}

Queries & Mutations

Queries are used to request data from the API, and Mutations are used to modify data. See examples in the API Playground section.

API Endpoints

You can query your data at the following endpoints:

• Production: https://api-production.mortgagehippo.com/graphql

• Staging: https://api-staging.mortgagehippo.com/graphql

Before you can access the API we must provide you with an authorization token to be passed in the request's HTTP header.

"Authorization": "Bearer YOUR_TOKEN"