> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  After you submit KYC information, switch to the [KYC
  Status](/docs/users/features/kyc-status) endpoint to monitor review progress
  and any remaining blockers.
</Info>

## 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

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

<ResponseField name="userId" type="string" required>
  Path parameter. Provide the target user ID (UUID).
</ResponseField>

<ResponseField name="rails" type="enum<string>" required>
  Query parameter. Specify the rail to unlock — `USD`, `AFRICA_GENERAL`,
  `AFRICA_NIGERIA`, or `GLOBAL_NETWORK`.
</ResponseField>

## Response Structure

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

```json expandable theme={null}
[
  {
    "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

<ResponseField name="userId" type="string" required>
  Unique identifier for the user. Always returned for context, even when the
  user has no invalid fields.
</ResponseField>

<ResponseField name="rails" type="string" required>
  The rail the requirements apply to. Matches the `rails` query parameter.
</ResponseField>

<ResponseField name="type" type="string" required>
  Indicates the user type. Possible values are `business` and `individual`.
</ResponseField>

### 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.

<ResponseField name="required" type="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.

  <Expandable title="properties">
    <ResponseField name="fields" type="object">
      Scalar requirements keyed by field name (for example `businessName`, `taxIdentificationNumber`).
    </ResponseField>

    <ResponseField name="documents" type="object">
      Document groups that must be satisfied.

      <Expandable title="Document group">
        <ResponseField name="minCount" type="integer">
          Minimum number of files required for that group.
        </ResponseField>

        <ResponseField name="acceptedDocTypes" type="array[string]">
          Allowed document identifiers. The applicant must upload at least `minCount` files from this list.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ultimateBeneficialOwners" type="array[object]">
      Present for business profiles. Each entry lists the data and documentation required for a specific UBO.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="optional" type="object">
  Fields and document groups that improve submission quality but are not
  mandatory.

  <Expandable title="properties">
    <ResponseField name="fields" type="object">
      Optional scalar fields that may unlock higher limits or smoother reviews.
    </ResponseField>

    <ResponseField name="documents" type="object">
      Optional document groups following the same structure as required document groups.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="invalid" type="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.

  <Expandable title="properties">
    <ResponseField name="message" type="string">
      High-level explanation of what still blocks submission.
    </ResponseField>

    <ResponseField name="fields" type="object">
      Each property corresponds to an invalid field with the reason (`missing`, `invalid_format`, etc.).
    </ResponseField>

    <ResponseField name="documents" type="object">
      Structured document feedback that mirrors the document-group schema.

      <Expandable title="Document validation">
        <ResponseField name="message" type="string">
          Human-readable summary of which groups need attention.
        </ResponseField>

        <ResponseField name="groups" type="object">
          Per-group validation using the `minCount`/`acceptedDocTypes` format so you can surface the exact requirements still outstanding.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 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. |

<Info>
  Only documents uploaded through the Documents API count toward these
  requirements.
</Info>

## 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.

<Tabs>
  <Tab title="Business (USD)">
    ```json expandable theme={null}
    {
      "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.
  </Tab>

  <Tab title="Individual (USD)">
    ```json expandable theme={null}
    {
      "userId": "35dbc7ea-2877-4a70-add6-b5458289df23",
      "rails": "USD",
      "type": "individual",
      "required": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phone": "string",
        "nationality": "string",
        "dateOfBirth": "string",
        "address": {
          "required": {
            "addressLine1": "string",
            "city": "string",
            "stateProvinceRegion": "string",
            "postalCode": "string",
            "country": "string"
          },
          "optional": {
            "addressLine2": "string"
          }
        },
        "taxIdentificationNumber": "string",
        "documents": {
          "identity": {
            "minCount": 1,
            "acceptedDocTypes": [
              "DRIVERS",
              "ID_CARD",
              "PASSPORT",
              "RESIDENCE_PERMIT"
            ]
          },
          "proofOfResidence": {
            "minCount": 1,
            "acceptedDocTypes": [
              "UTILITY_BILL",
              "BANK_STATEMENT",
              "GOVERNMENT_LETTER"
            ]
          }
        }
      },
      "optional": {
        "sofEuQuestionnaire": {
          "required": {
            "actingAsIntermediary": "string",
            "employmentStatus": "string",
            "expectedMonthlyPayments": "string",
            "mostRecentOccupation": "string",
            "primaryPurpose": "string",
            "sourceOfFunds": "string"
          },
          "optional": {
            "primaryPurposeOther": "string"
          }
        }
      },
      "invalid": {
        "message": "fields are either missing or invalid",
        "fields": {
          "phone": "missing",
          "nationality": "missing",
          "taxIdentificationNumber": "missing"
        },
        "documents": {
          "message": "The following document groups are not satisfied: identity",
          "groups": {
            "identity": {
              "minCount": 1,
              "acceptedDocTypes": [
                "DRIVERS",
                "ID_CARD",
                "PASSPORT",
                "RESIDENCE_PERMIT"
              ]
            }
          }
        }
      }
    }
    ```

    **What to watch for**

    * **Identity documents**: Individuals must always satisfy the `identity` document group. If `minCount` is `1`, at least one document from the accepted list must be present.
    * **Proof of residence**: Some rails require the `proofOfResidence` group; when it is optional it will surface in the `optional` object instead.
    * **Invalid messages**: Use `invalid.fields` to highlight missing form inputs and `invalid.documents.message` for UI copy explaining outstanding document groups.
  </Tab>
</Tabs>

## Next Steps

* After all required fields and documents are satisfied, call [Submit KYC](https://docs.hifi.com/api-reference/kyc/submit-kyc).
* Use the [KYC Status guide](/docs/users/features/kyc-status) to interpret post-submission results and remediation steps.