GuidesAPI ReferenceDiscussions
HomeGuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceDiscussions

API Quick Start Guide

Suggest Edits

Introduction

With this quickstart guide, we’ve tried to make it as easy as possible to get up and running with Blend’s Public API.

Getting Started

Download the OpenAPI Specs and Postman Collection

The quickest way to explore the capabilities of our API is to download the OpenAPI specification. This can be used in conjunction with open source tooling to auto-generate code stubs, tests, and other helpful snippets to speed your development along.

If you'd like to test the API directly before you begin development, we also provide an importable Postman collection that, combined with the authentication and authorization data you'll get from completing the "Getting Started" steps below, will allow you to make your first call with just a few simple clicks of your mouse!

You can always visit our publicly available blend-api-specs Github page for the latest specs and collections.

Auth Token

In order to get your API token:

To learn more about Blend's Auth Paradigm check out Blend's API Technical Standards and Formats and our API Auth Security Details.

Environments

We provide the following environments per Integrator organization:

Which environment you want to operate in will determine part of the base structure of your route URLs.

Target Instance

When you initially request your credentials, we will give you the appropriate blend-target-instance for that environment. The target instance header consists of up to two parts depending on the environment:

For production, this will take the form of a string such as yourTenantName.

{ "blend-target-instance": "yourTenantName" }

For sub-production environments (e.g. beta or test), Blend uses an instance identifier to allow for multiple streams of concurrent development in certain cases. As such, the blend-target-instance will always take the form of a tenant identifier concatenated with an instance identifier by a tilde (~). For most integrators, the instance identifier will simply be default.

// Default case: a single tenant
{ "blend-target-instance": "yourTenantName~default" }

// Special case: multiple instances per tenant
{ "blend-target-instance": "yourTenantName~yourInstanceId" }

In all cases, Blend will provide the appropriate per-environment values to you during the integration setup process.

Version Header

Every call should include a blend-api-version header. This allows you to pin calls to a specific version of Blend's API that you have confirmed they work with and prevent unexpected changes from happening. Additionally, it allows you to tackle updates in a rolling fashion across your integration.

For example, if there is a new feature in the parties route you want to take advantage of, you can upgrade your parties calls to the next version (e.g. 3.1.0) without necessarily having to update all your other calls to the applications, documents, disclosures and reporting routes that are still on v3.0.0.

Review Basic Request Formatting

Check out Blend's API Technical Standards and Formats to understand the how Blend's API is constructed, and what kind of authentication and data formats it accepts.

Your First API Call

All API calls include at least 4 pieces:

  • Route
  • Auth Token
  • Target Instance
  • Version

Additionally, POST, PUT and PATCH calls will also include a Request Body.

Example

curl -X GET \
https://api.beta.blendlabs.com/home-lending/applications \
-H 'authorization: BEARER {{YOUR AUTH TOKEN}}' \
-H 'blend-target-instance: {{YOUR BLEND DEPLOYMENT}}~{{YOUR SPECIAL ID}}' \
-H 'blend-api-version: 3.0.0' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \

Error Messages

All error scenarios where our server is able to respond to you will have the following error response object:

{
  error: ‘internal error message’,
  display: ‘user friendly error message’,
  trackingId: ‘23123’
}

You can use the error and display fields to diagnose any non-500 error statuses and handle the errors appropriately. Check out Blend's API Technical Standards and Formats to understand what kind of errors you are likely to see.

If you get a 500 error or need any further assistance, please provide the error and trackingId along with the API call you attempted to make in a message to [email protected] to be able to triage your issue quickly and efficiently.

If you need to display an error message to end-users of your integration, we recommend that you pass through the display field (NOT the error field), which will include the appropriate information to prompt a user to be able to resolve their issue themselves or contact the Blend support team with additional context.

Migrating to Production

Partners: Due Diligence Questionnaire

In order to migrate to production, you must fill out the Blend's Partner Due Diligence Questionnaire, and submit it for Blend review.

After Blend has reviewed the contents with the relevant Infosec, compliance, and implementation stakeholders, we will provide recommendations as needed and approve the request for production API credentials.

Once you have this review completed, you can request access to a specific customer's beta environment to set-up and test with that customer, and then request access to their production environment once the customer is ready to go live with the new integrations. See "Moving to Production" below for more info.

Customers that have signed the MSA Addendum with Blend do not have to fill out this Questionnaire.

Customers & Partners: IP whitelisting

Additionally, IP whitelisting is a requirement before moving to production. Requests with valid Auth Tokens, Target Instances, and Access will still fail if they come from IPs that are not whitelisted with Blend.

Getting Help

Take a look at any of the Developer Guides here or contact us at [email protected] if you have any questions.

Updated over 1 year ago