Skip to main content
All HIFI API endpoints return structured JSON responses containing the requested data. Understanding the response format and how to work with API responses is essential for building reliable integrations.

​
Response Format

API responses follow a consistent JSON structure. Most endpoints return data directly, while some return paginated lists or nested objects. The exact structure depends on the endpoint and any query parameters you use. Example response: 
{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz"
  }
}

​
Response Properties

By default, API responses include:
  • Direct properties of the requested object
  • IDs for related objects (which require additional API calls to fetch full details)
  • Status and metadata relevant to the request
This design keeps responses lightweight and allows you to fetch related data only when needed. The HIFI API supports expanding related objects in responses to reduce API calls and improve efficiency. Instead of making multiple requests to fetch related data, you can use the expand parameter to include nested objects directly in a single response.

​
How Expansion Works

By default, API responses include only basic object properties and IDs for related objects. When you use the expand parameter, the API replaces these IDs with the full related objects, including all their properties. Example without expansion: 
{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz",
    "ultimateBeneficialOwners": [
      "1f432735-24fa-4c72-8f99-37c540206688",
      "393edc1e-6c8d-4d6e-a924-4b7c28c29a70"
    ]
  }
}
Example with expansion: 
{
  "userId": "6513dcd0-2161-4d18-bdca-c1ef94ebf21d",
  "kycInfo": {
    "type": "business",
    "businessName": "Random Bizz",
    "ultimateBeneficialOwners": [
      {
        "id": "1f432735-24fa-4c72-8f99-37c540206688",
        "firstName": "William",
        "lastName": "Y",
        "email": "william@example.com",
        "documents": [
          {
            "id": "a36920a2-2bb6-4d24-b1ca-e3cca39bd33a",
            "type": "PASSPORT",
            "subType": "FRONT_SIDE",
            "url": "example.com"
          }
        ]
      }
    ]
  }
}

​
KYC Endpoints

​
Update KYC Endpoint

POST /v2/users/{userId}/kyc When updating KYC information, you can expand related objects to get immediate access to updated data: 
curl -X POST "https://production.hifibridge.com/v2/users/{userId}/kyc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+8573491112",
    "taxIdentificationNumber": "564213816"
  }' \
  "?expand[]=ultimateBeneficialOwners&expand[]=documents&expand[]=ultimateBeneficialOwners.documents"
Supported expansions:
  • ultimateBeneficialOwners - Include full UBO objects
  • documents - Include all KYC documents
  • ultimateBeneficialOwners.documents - Include documents for each UBO

​
Retrieve KYC Information

GET /v2/users/{userId}/kyc Retrieve KYC information with expanded related objects: 
curl -X GET "https://production.hifibridge.com/v2/users/{userId}/kyc?expand[]=ultimateBeneficialOwners&expand[]=documents&expand[]=ultimateBeneficialOwners.documents" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use cases:
  • Display complete KYC status including UBO details
  • Show all associated documents in a single request
  • Access nested document information for each UBO

​
UBO Endpoints

​
Add a UBO

POST /v2/users/{userId}/kyc/ultimateBeneficialOwners When adding a new UBO, expand documents to immediately see associated documents: 
curl -X POST "https://production.hifibridge.com/v2/users/{userId}/kyc/ultimateBeneficialOwners" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }' \
  "?expand[]=documents"
Supported expansions:
  • documents - Include all documents for the UBO

​
Update a UBO

PUT /v2/users/{userId}/kyc/ultimateBeneficialOwners/{uboId} Update UBO information with expanded document details: 
curl -X PUT "https://production.hifibridge.com/v2/users/{userId}/kyc/ultimateBeneficialOwners/{uboId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1234567890"
  }' \
  "?expand[]=documents"

​
Retrieve a UBO

GET /v2/users/{userId}/kyc/ultimateBeneficialOwners/{uboId} Get specific UBO details with expanded documents: 
curl -X GET "https://production.hifibridge.com/v2/users/{userId}/kyc/ultimateBeneficialOwners/{uboId}?expand[]=documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
List all UBOs

GET /v2/users/{userId}/kyc/ultimateBeneficialOwners Retrieve all UBOs with their associated documents: 
curl -X GET "https://production.hifibridge.com/v2/users/{userId}/kyc/ultimateBeneficialOwners?expand[]=documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
API Reference

For complete details on which endpoints support expansion and which properties are expandable, refer to the API Reference.