Custom Fields and Metadata on Resources

Overview

What problem are we trying to solve?

From time to time, Blend customers may need to add their own custom IDs to various resources for different purposes (e.g., to track the ID of a resource in an external software system). These custom ID fields could be added directly into our core data models, but Blend has so many customers that these models would quickly become bloated. To keep this functionality scalable and flexible, the newly added custom fields and metadata must be decoupled from the existing data model.

How are we solving it?

In version 4.1.0, Custom Fields, a framework that allowed users to attach their own custom string key-value pairs to Blend resources, was introduced. While Custom Fields worked for most customers' needs, it was limited in that users could only add a given key-value pair once in a set of resources (e.g., you could not set losId=12345 on two different applications, documents, etc.). In version 4.3.0, Custom Metadata was added to support this additional functionality. Customers can add a given key-value pair unlimited times across different resources in the Custom Metadata section of their requests, which is helpful for tagging (e.g. loanType=home). The following sections will explain in detail on how to use the Custom Fields and Custom Metadata functionality using GET, POST and PATCH requests.

📘

Custom Fields vs. Custom Metadata - Summary

• Users may only add a given key-value pair to Custom Fields once across a given set of resources (e.g. applications, documents), and users can query resources by Custom Fields key-value pairs.
• Users may add a given key-value pair to Custom Metadata an unlimited amount of times across a given set of resources, but users cannot query resources by Custom Metadata key-value pairs.
• Users cannot add the same key across Custom Fields and Custom Metadata for a given resource. For example, adding losId=123 to Custom Fields and losId=1234 to Custom Metadata for a single loan application would fail.
• Any custom field or metadata entry can be deleted by setting the field/metadata value entry to the string "null" in a PATCH request.

Which resources support custom fields and metadata?

The API resources supported as of now are:

• Applications
• Parties
• Documents

User Actions & Examples

Users will be able to take the following actions:

1. Users will be able to pass in custom fields and custom metadata on PATCH or POST requests to supported resources. The fields and metadata will be provided as an object on the request body of the following format:

customFields: {
  fieldName_1: fieldValue_1,
  fieldName_2: fieldValue_2
},
customMetadata: {
  metadataName_1: metadataValue_1,
  metadataName_2: metadataValue_2
}

2. Users will be able to query by custom field value for an exact match on a GET request for supported resources (NOTE: querying is not supported for custom metadata). The query params will be identified by a pre-defined prefix and will look like:

curl --X GET https://api.blend.com/home-lending/applications?custom_field_query=<field_name>=<field_value>

The output will yield the matching resource (if one exists), with all the custom fields on the GET request, in the sub-object format given below:

customFields: {
  fieldName_1: {
    value: fieldValue_1,
    createdAt: "2020-12-10T17:49:33.675Z",
  }, 
  fieldName_2: {
    value: fieldValue_2,
    createdAt: "2020-12-10T17:49:33.675Z",
  }
}

📘

Some prerequisites

• Field names can only contain letters (upper or lower case), numbers, underscores, dashes, periods, forward slashes, pound signs, and plus signs. This restriction applies to both Custom Fields and Custom Metadata.
• Field names are limited to 100 characters.
• Users will only be able to query for a single field key-value pair.
• The total amount of data in Custom Fields for a given resource cannot exceed 10kB, and cannot exceed 50kB for Custom Metadata.

Examples

1. GET home-lending/applications?custom_field_query=<field_name>=<field_value>

curl --X GET 'https://api.blend.com/home-lending/applications?custom_field_query=losPartyId=LOS123' \
--H 'blend-api-version: 4.3.0' \

2. POST home-lending/applications

curl --X POST 'https://api.blend.com/home-lending/applications' \
--H 'blend-api-version: 4.3.0' \
--d '{
    "party": {
        "name": {
            "firstName": "Jane",
            "lastName": "Doe"
        },
        "email": "[email protected]",
        "taxpayerIdentifier": {
            "value": "151313231",
            "type": "SOCIAL_SECURITY_NUMBER"
        },
        "SSN": "000144433",
        "dateOfBirth": "1981-01-01",
        "homePhone": "1112253233",
        "currentAddress": {
            "streetAddressLine1": "100 Main St",
            "streetAddressLine2": "Apt 10",
            "city": "Chicago",
            "state": "IL",
            "zipCode": "60007"
        }
    },
    "loanType": "MORTGAGE",
    "loanPurposeType": "PURCHASE",
    "loanAmount": "100000",
    "communityId": "LOAS-333",
    "leadId": "leadId1",
    "crmId": "crmLead1",
    "losId": "Loan-12391",
    "referenceNumber": "124123",
    "sendEmailInvite": "true",
    "applicationTemplateId": "fd658b97-f901-4b14-b693-4654d276c909",
    "customFields": {
        "losPartyId": "LO011abcId"
    },
    "customMetadata": {
        "applicationType": "type123"
    }
}'

3. PATCH home-lending/applications

curl --X PATCH 'https://api.blend.com/home-lending/applications/9d531957-37eb-4ebf-8c6a-77d1b1dfdfb5' \
--H 'blend-api-version: 4.3.0' \
-d  '{
    "customFields": {
        "fieldId": "f123Id"
    },
    "customMetadata": {
        "applicationType": "type123"
    }
}'

3. PATCH home-lending/applications (field deletion)

curl --X PATCH 'https://api.blend.com/home-lending/applications/9d531957-37eb-4ebf-8c6a-77d1b1dfdfb5' \
--H 'blend-api-version: 4.3.0' \
-d  '{
    "customFields": {
        "fieldId": "null"
    },
    "customMetadata": {
        "applicationType": "null"
    }
}'

🚧

Warning:

• Using invalid field key names may return the following error message: (400) Bad Request response status code