This guide describes how to request additional properties from the API. You will learn to modify your requests to include:

properties from related objects
properties from distantly related objects
additional properties on all objects in a list
properties that aren’t included by default in a response

How it works

The HIFI API is organized into resources represented by objects with state, configuration, and contextual properties. These objects all have unique IDs that you can use to retrieve, update, and delete them. The API also uses these IDs to link related objects together.

{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz",
    "ultimateBeneficialOwners": [
      "1f432735-24fa-4c72-8f99-37c540206688",
      "393edc1e-6c8d-4d6e-a924-4b7c28c29a70"
    ]
  }
}

In cases where you need information from a linked object, you can retrieve the linked object in a new call using its ID. However, this approach requires two API requests to access just one value. If you need information from multiple linked objects, each would also require separate requests, which all adds to the latency and complexity of your application.

The API has an Expand feature that allows you to retrieve linked objects in a single call, effectively replacing the object ID with all its properties and values. For example, say you wanted to access details on a "ultimateBeneficialOwners" tied to a given KYC object. You would retrieve the KYC object and pass the "ultimateBeneficialOwners" property to the expand array, which tells HIFI to include the entire UBO object in the response:

curl --request GET \
     --url https://production.hifibridge.com/v2/users/9438e327-29c8-4ca2-8e78-7b0df013f928/kyc?&expand[]=ultimateBeneficialOwners

Which returns the KYC object with the full UBO object instead of its ID:

{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz",
    "ultimateBeneficialOwners": [
      {
        "id": "1f432735-24fa-4c72-8f99-37c540206688",
        "firstName": "William",
        "lastName": "Y",
        "email": "[email protected]"
      },
      {
        "id": "393edc1e-6c8d-4d6e-a924-4b7c28c29a70",
        "firstName": "Henry",
        "lastName": "W",
        "email": "[email protected]"
      }
    ]
  }
}

Note

Not all properties can be expanded. The API reference marks expandable properties with the “Expandable” label.

Expanding multiple properties

To expand multiple properties in one call, add additional items to the expand array. For example, if you want to expand both the "ultimateBeneficialOwners" and the "documents" for a given KYC Object, you would pass expand an array with both the "ultimateBeneficialOwners" and "documents" strings:

curl --request GET \
     --url https://production.hifibridge.com/v2/users/9438e327-29c8-4ca2-8e78-7b0df013f928/kyc?&expand[]=ultimateBeneficialOwners&expand[]=documents

Expanding multiple levels

If the value you want is nested deeply across multiple linked resources, you can reach it by recursively expanding using dot notation. For instance, if you needed to know the "documents" for each "ultimateBeneficialOwners", you would first retrieve the "ultimateBeneficialOwners", then retrieve each "documents". With expand, you can do this in one call:

curl --request GET \
     --url https://production.hifibridge.com/v2/users/9438e327-29c8-4ca2-8e78-7b0df013f928/kyc?&expand[]=ultimateBeneficialOwners.documents

Which returns the UBOs with the full Document objects instead of their IDs:

{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz",
    "ultimateBeneficialOwners": [
      {
        "id": "1f432735-24fa-4c72-8f99-37c540206688",
        "firstName": "William",
        "lastName": "Y",
        "email": "[email protected]",
        "documents": [
          {
            "id": "a36920a2-2bb6-4d24-b1ca-e3cca39bd33a",
            "type": "PASSPORT",
            "subType": "FRONT_SIDE",
            "url": "example.com"
          },
          {
            "id": "9e1ca8fe-aea4-4433-8125-f319bb423fd8",
            "type": "PASSPORT",
            "subType": "BACK_SIDE",
            "url": "example.com"
          }
        ]
      },
      {
        "id": "393edc1e-6c8d-4d6e-a924-4b7c28c29a70",
        "firstName": "Henry",
        "lastName": "W",
        "email": "[email protected]",
        "documents": [
          {
            "id": "d48cc2e7-4eec-4dda-8fde-8ce980913ed4",
            "type": "PASSPORT",
            "subType": "BACK_SIDE",
            "url": "example.com"
          },
          {
            "id": "a919de96-35cd-4c6b-8149-b0962fca1fe7",
            "type": "PASSPORT",
            "subType": "FRONT_SIDE",
            "url": "example.com"
          }
        ]
      }
    ]
  }
}