KYC Requirements

The KYC Requirements endpoint tells you exactly which data points and documents are needed to unlock a given rail for a specific user.

Use it before submitting KYC information so you can pre-fill forms, surface missing fields, and resolve issues.

After you submit KYC information, switch to the KYC Status endpoint to monitor review progress and any remaining blockers.

Usage

• Pre-fill onboarding flows with the precise set of fields per rail.
• Detect missing or invalid data before attempting a submission.
• Show document requirements (including minimum counts and accepted document types) to users or operators.

Request Overview

Request

GET https://sandbox.hifibridge.com/v2/users/{userId}/kyc/requirements?rails=USD
Authorization: Bearer <token>

userId · string · required

Path parameter. Provide the target user ID (UUID).

rails · enum<string> · required

Query parameter. Specify the rail to unlock — USD, AFRICA_GENERAL, AFRICA_NIGERIA, or GLOBAL_NETWORK.

You can submit requirements for multiple rails at the same time and get all requirements at once.

Response Structure

Below is an example of a 200 OK response for a USD business user:

[
  {
    "userId": "35dbc7ea-2877-4a70-add6-b5458289df23",
    "rails": "USD",
    "type": "business",
    "required": {
      "businessName": "string",
      "registeredAddress": "string",
      "documents": {
        "legalPresence": {
          "minCount": 1,
          "acceptedDocTypes": ["INCORPORATION_CERT"]
        }
      }
    },
    "optional": {
      "incorporationState": "string"
    },
    "invalid": {
      "fields": {
        "taxIdentificationNumber": "missing"
      },
      "documents": {
        "message": "The following document groups are not satisfied: ownershipStructure"
      }
    }
  }
]

The response has a standard shape:

• top-level identifiers to anchor the entry (userId, rails, type)
• three requirement buckets (required, optional, invalid)
• reusable document-group metadata.

Walk through the sections below to understand this structure.

Top-level fields

userId · string · required

Unique identifier for the user. Always returned for context, even when the user has no invalid fields.

rails · string · required

The rail the requirements apply to. Matches the rails query parameter.

type · string · required

Indicates the user type. Possible values are business and individual.

Requirement Buckets

The required, optional, and invalid objects share the same internal layout. They differ only in intent—what must be supplied now, what enhances the submission, and what is missing today.

required · object · required

Complete list of fields that must be populated before submitting KYC for the selected rail and profile. Fields appear only when they are required.

Show properties

fields · object

Scalar requirements keyed by field name (for example businessName, taxIdentificationNumber).

documents · object

Document groups that must be satisfied.

Show Document group

minCount · integer

Minimum number of files required for that group.

acceptedDocTypes · array[string]

Allowed document identifiers. The applicant must upload at least minCount files from this list.

ultimateBeneficialOwners · array[object]

Present for business profiles. Each entry lists the data and documentation required for a specific UBO.

optional · object

Fields and document groups that improve submission quality but are not mandatory.

Show properties

fields · object

Optional scalar fields that may unlock higher limits or smoother reviews.

documents · object

Optional document groups following the same structure as required document groups.

invalid · object

Any fields or document groups that the user currently has but are missing or invalid for this rail. If the user has not provided data yet, this object may be empty.

Show properties

message · string

High-level explanation of what still blocks submission.

fields · object

Each property corresponds to an invalid field with the reason (missing, invalid_format, etc.).

documents · object

Structured document feedback that mirrors the document-group schema.

Show Document validation

message · string

Human-readable summary of which groups need attention.

groups · object

Per-group validation using the minCount/acceptedDocTypes format so you can surface the exact requirements still outstanding.

Document Groups

Document groups appear anywhere documents are referenced (required.documents, optional.documents, and invalid.documents.groups). Each group specifies a minimum number of files and the accepted document types.

Property	Type	Description
minCount	integer	Minimum number of documents needed for that group.
acceptedDocTypes	array	Accepted document identifiers; the user must provide at least minCount documents from this list.

Only documents uploaded through the Documents API count toward these requirements.

Response Breakdown

The structure under required, optional, and invalid changes depending on whether the user is a business or an individual. Use the tabs below to explore both shapes.

Business (USD)

{
  "userId": "35dbc7ea-2877-4a70-add6-b5458289df23",
  "rails": "USD",
  "type": "business",
  "required": {
    "businessName": "string",
    "businessType": "string",
    "businessIndustry": "string",
    "registrationNumber": "string",
    "registeredAddress": "string",
    "address": {
      "required": {
        "addressLine1": "string",
        "city": "string",
        "stateProvinceRegion": "string",
        "postalCode": "string",
        "country": "string"
      },
      "optional": {
        "addressLine2": "string"
      }
    },
    "website": "string",
    "incorporationDate": "date",
    "email": "string",
    "phone": "string",
    "taxIdentificationNumber": "string",
    "sofEuQuestionnaire": {
      "required": {
        "primaryPurpose": "string",
        "sourceOfFunds": "string",
        "transmitsCustomerFunds": "boolean",
        "conductsMoneyServices": "boolean",
        "highRiskActivities": "array",
        "estimatedAnnualRevenueUsd": "string",
        "expectedMonthlyPaymentsUsd": "string",
        "customerFundsDescription": "string"
      },
      "optional": {
        "operatesInProhibitedCountries": "string",
        "primaryPurposeOther": "string",
        "sourceOfFundsDescription": "string",
        "transmitsCustomerFundsDescription": "string"
      }
    },
    "ultimateBeneficialOwners": [
      {
        "required": {
          "roles": "array",
          "businessTitle": "string",
          "firstName": "string",
          "lastName": "string",
          "nationality": "string",
          "email": "string",
          "phone": "string",
          "address": {
            "required": {
              "addressLine1": "string",
              "city": "string",
              "stateProvinceRegion": "string",
              "postalCode": "string",
              "country": "string"
            },
            "optional": {
              "addressLine2": "string"
            }
          },
          "taxIdentificationNumber": "string",
          "dateOfBirth": "date",
          "shareProportion": "string",
          "relationshipEstablishedAt": "date",
          "documents": {
            "identity": {
              "minCount": 1,
              "acceptedDocTypes": [
                "DRIVERS",
                "ID_CARD",
                "PASSPORT",
                "RESIDENCE_PERMIT"
              ]
            }
          }
        },
        "optional": {
          "middleName": "string"
        }
      }
    ],
    "documents": {
      "legalPresence": {
        "minCount": 1,
        "acceptedDocTypes": [
          "INCORPORATION_ARTICLES",
          "INCORPORATION_CERT",
          "STATE_REGISTRY"
        ]
      },
      "ownershipStructure": {
        "minCount": 1,
        "acceptedDocTypes": [
          "SHAREHOLDER_REGISTRY",
          "TRUST_AGREEMENT",
          "INFORMATION_STATEMENT",
          "STATE_REGISTRY"
        ]
      },
      "companyDetails": {
        "minCount": 1,
        "acceptedDocTypes": [
          "PROOF_OF_ADDRESS"
        ]
      },
      "controlStructure": {
        "minCount": 1,
        "acceptedDocTypes": [
          "DIRECTORS_REGISTRY",
          "TRUST_AGREEMENT",
          "INFORMATION_STATEMENT",
          "STATE_REGISTRY"
        ]
      }
    }
  },
  "optional": {
    "incorporationCountry": "string",
    "incorporationState": "string"
  },
  "invalid": {
    "message": "fields are either missing or invalid",
    "fields": {
      "registrationNumber": "missing"
    },
    "documents": {
      "message": "The following document groups are not satisfied: controlStructure",
      "groups": {
        "controlStructure": {
          "minCount": 1,
          "acceptedDocTypes": [
            "DIRECTORS_REGISTRY",
            "TRUST_AGREEMENT",
            "INFORMATION_STATEMENT",
            "STATE_REGISTRY"
          ]
        }
      }
    }
  }
}

What to watch for

• Ultimate Beneficial Owners (UBOs): Each UBO must meet the same address, identity, and questionnaire requirements as an individual. If any UBO document is missing, the requirement appears under invalid.documents.groups.
• Document groups: All four groups (legalPresence, ownershipStructure, companyDetails, controlStructure) must satisfy minCount. The response repeats accepted document types, so you can render them directly in an operator dashboard.
• SofEu questionnaire: Every field listed under required must be supplied. Optional fields only appear when they are relevant to the rail.

Next Steps

• After all required fields and documents are satisfied, call Submit KYC.
• Use the KYC Status guide to interpret post-submission results and remediation steps.