> ## 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. # Retrieve KYC requirements > Get the required and optional KYC fields for a specific rail, along with any invalid KYC fields currently held by the user for unlocking the rail. The Get KYC Requirements endpoint provides a comprehensive list of required and optional KYC fields needed to initiate a KYC submission (the same set of info available in our [Compliance Guide](https://docs.hifi.com/docs/rails/overview)). Additionally, it identifies any invalid fields in the user's current KYC data that need to be updated before submission. This is particularly useful for pre-filling KYC forms and addressing issues proactively. This endpoint is intended **only** for use **before** KYC submission. After submitting KYC data, use the [Retrieve KYC status](https://docs.hifi.com/api-reference/kyc/retrieve-kyc-status) endpoint to check the submission status and further identify any fields that may still require updates. ## OpenAPI ````yaml https://production.hifi.com/api/v2/openapi.json get /v2/users/{userId}/kyc/requirements openapi: 3.0.0 info: title: Hifi API version: 2.0.0 description: API documentation for Hifi servers: - url: https://production.hifibridge.com description: Production server - url: https://sandbox.hifibridge.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Kyc description: Kyc endpoints - name: Wallet description: Wallet endpoints - name: Account description: Account endpoints - name: External Account description: External Account endpoints for managing beneficiary bank accounts - name: Fiat Account description: Fiat Account endpoints - name: Virtual Account description: Virtual Account endpoints - name: Onramp description: Onramp endpoints - name: Offramp description: Offramp endpoints - name: Orchestration Address description: >- Orchestration Address endpoints — persistent on-chain wallets that automatically off-ramp incoming stablecoin deposits to a USD bank account - name: Crypto Transfer description: Crypto Transfer endpoints - name: Cross-Chain Bridge description: Cross-Chain Bridge endpoints - name: Token Swap description: Token Swap endpoints - name: Canton Offers description: Canton Offers endpoints - name: Transfer Rules description: Transfer approval rules and configuration - name: Transfer Approvals description: Transfer approval workflow and admin actions - name: File description: File endpoints - name: Reporting description: Reporting and metrics endpoints paths: /v2/users/{userId}/kyc/requirements: get: tags: - Kyc summary: Retrieve KYC requirements description: > Get the required and optional KYC fields for a specific rail, along with any invalid KYC fields currently held by the user for unlocking the rail. The Get KYC Requirements endpoint provides a comprehensive list of required and optional KYC fields needed to initiate a KYC submission (the same set of info available in our [Compliance Guide](https://docs.hifi.com/docs/rails/overview)). Additionally, it identifies any invalid fields in the user's current KYC data that need to be updated before submission. This is particularly useful for pre-filling KYC forms and addressing issues proactively. This endpoint is intended **only** for use **before** KYC submission. After submitting KYC data, use the [Retrieve KYC status](https://docs.hifi.com/api-reference/kyc/retrieve-kyc-status) endpoint to check the submission status and further identify any fields that may still require updates. parameters: - $ref: '#/components/parameters/UserIdPathParameter' - $ref: '#/components/parameters/RailsTypeParameter' responses: '200': $ref: '#/components/responses/KycRequirementResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: parameters: UserIdPathParameter: name: userId in: path schema: type: string description: ID of the user required: true RailsTypeParameter: name: rails in: query schema: $ref: '#/components/schemas/RailsEnum' required: true responses: KycRequirementResponse: description: Success content: application/json: schema: oneOf: - $ref: '#/components/schemas/USDRailBusinessKYCReqOptObject' - $ref: '#/components/schemas/USDRailIndividualKYCReqOptObject' examples: KycRequirementObjectBusinessUSDExample: $ref: '#/components/examples/KycRequirementObjectBusinessUSDExample' KycRequirementObjectIndividualUSDExample: $ref: '#/components/examples/KycRequirementObjectIndividualUSDExample' UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Resource not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: RailsEnum: type: string description: The type of rail. enum: - USD - SOUTH_AMERICA_STANDARD - AFRICA_GENERAL - AFRICA_NIGERIA - GLOBAL_NETWORK - USD_FIAT USDRailBusinessKYCReqOptObject: type: object title: KYC Requirement Object (USD - Business) properties: userId: type: string format: uuid rails: $ref: '#/components/schemas/RailsEnum' type: type: string enum: - business required: type: object description: >- KYC fields required for this rail. The required fields varies based on the Rail. properties: businessName: type: string businessType: type: string businessIndustry: type: string registrationNumber: type: string registeredAddress: type: string address: $ref: '#/components/schemas/AddressReqOptObject' website: type: string incorporationDate: type: string email: type: string phone: type: string taxIdentificationNumber: type: string sofEuQuestionnaire: $ref: '#/components/schemas/SofEuQaKybReqOptObject' ultimateBeneficialOwners: type: array documents: $ref: '#/components/schemas/USDRailBusinessDocReqOptObject' optional: type: object description: >- KYC fields that are optional for this rail. The optional fields varies based on the Rail. properties: incorporationCountry: type: string incorporationState: type: string invalid: type: object description: >- KYC fields the user currently holds that are either missing or invalid for this rail. The specific invalid fields vary depending on the user’s current KYC data. properties: message: type: string fields: type: object description: >- Any missing or invalid fields, which varies depending on the user’s current KYC data. properties: registrationNumber: type: string documents: type: object description: >- Any missing documents groups, which varies depending on the user’s current KYC documents data. properties: message: type: string groups: type: object properties: controlStructure: type: object properties: minCount: type: integer acceptedDocTypes: type: array items: type: string USDRailIndividualKYCReqOptObject: type: object title: KYC Requirement Object (USD - Individual) properties: userId: type: string format: uuid rails: $ref: '#/components/schemas/RailsEnum' type: type: string enum: - individual required: type: object description: >- KYC fields required for this rail. The required fields varies based on the Rail. properties: firstName: type: string lastName: type: string email: type: string phone: type: string nationality: type: string dateOfBirth: type: string address: $ref: '#/components/schemas/AddressReqOptObject' taxIdentificationNumber: type: string documents: $ref: '#/components/schemas/USDRailIndividualDocReqOptObject' optional: type: object description: >- KYC fields that are optional for this rail. The optional fields varies based on the Rail. properties: sofEuQuestionnaire: $ref: '#/components/schemas/SofEuQaKycReqOptObject' invalid: type: object description: > KYC fields the user currently holds that are either missing or invalid for this rail. The specific invalid fields vary depending on the user’s current KYC data. properties: message: type: string fields: type: object description: >- Any missing or invalid fields, which varies depending on the user’s current KYC data. properties: phone: type: string nationality: type: string taxIdentificationNumber: type: string documents: type: object description: >- Any missing documents groups, which varies depending on the user’s current KYC documents data. properties: message: type: string groups: type: object properties: identity: type: object properties: minCount: type: integer acceptedDocTypes: type: array items: type: string Unauthorized: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message InternalServerError: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message AddressReqOptObject: type: object title: Address Requirement properties: required: type: object properties: addressLine1: type: string city: type: string stateProvinceRegion: type: string postalCode: type: string country: type: string optional: type: object properties: addressLine2: type: string SofEuQaKybReqOptObject: type: object title: SofEuQuestionnaire Requirement (Business) properties: required: type: object properties: primaryPurpose: type: string sourceOfFunds: type: string transmitsCustomerFunds: type: string conductsMoneyServices: type: string highRiskActivities: type: string estimatedAnnualRevenueUsd: type: string expectedMonthlyPaymentsUsd: type: string customerFundsDescription: type: string optional: type: object properties: operatesInProhibitedCountries: type: string primaryPurposeOther: type: string sourceOfFundsDescription: type: string transmitsCustomerFundsDescription: type: string USDRailBusinessDocReqOptObject: type: object title: Document Group Requirements (Business) properties: legalPresence: $ref: '#/components/schemas/DocGroupRequirementObject' ownershipStructure: $ref: '#/components/schemas/DocGroupRequirementObject' companyDetails: $ref: '#/components/schemas/DocGroupRequirementObject' controlStructure: $ref: '#/components/schemas/DocGroupRequirementObject' USDRailIndividualDocReqOptObject: type: object title: Document Group Requirements (Individual) properties: identity: $ref: '#/components/schemas/DocGroupRequirementObject' proofOfResidence: $ref: '#/components/schemas/DocGroupRequirementObject' SofEuQaKycReqOptObject: type: object title: SofEuQuestionnaire Requirement (Individual) properties: required: type: object properties: actingAsIntermediary: type: string employmentStatus: type: string expectedMonthlyPayments: type: string mostRecentOccupation: type: string primaryPurpose: type: string sourceOfFunds: type: string optional: type: object properties: primaryPurposeOther: type: string DocGroupRequirementObject: type: object title: Document Group Requirement description: > Represents minimum document requirements for a specific rail. Each group specifies the minimum number of documents required from a list of accepted document types. **Note: Only documents provided through the Documents Endpoint will be considered for fulfilling these requirements.** properties: minCount: type: integer description: | Minimum number of documents needed from the `acceptedDocTypes`. acceptedDocTypes: type: array description: > List of accepted document types. The user must provide at least `minCount` documents from this list. items: type: string countryRestrictions: type: object description: > Per-type country restrictions. When present for a document type, only documents of that type with an `issued_country` matching one of the listed ISO alpha-3 codes will satisfy this group. Document types not listed here have no country restriction. additionalProperties: type: array items: type: string examples: KycRequirementObjectBusinessUSDExample: summary: KYC Requirement Object (USD - Business) value: userId: 35dbc7ea-2877-4a70-add6-b5458289df23 rails: USD type: business required: businessName: string businessType: string businessIndustry: string registrationNumber: string registeredAddress: object 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: {} KycRequirementObjectIndividualUSDExample: summary: KYC Requirement Object (USD - Individual) value: userId: 35dbc7ea-2877-4a70-add6-b5458289df23 rails: USD type: individual required: firstName: string lastName: string email: string phone: string address: required: addressLine1: string city: string stateProvinceRegion: string postalCode: string country: string optional: addressLine2: string nationality: string dateOfBirth: string taxIdentificationNumber: string documents: identity: minCount: 1 acceptedDocTypes: - DRIVERS - ID_CARD - PASSPORT - RESIDENCE_PERMIT proofOfResidence: minCount: 1 acceptedDocTypes: - DRIVERS - ID_CARD - RESIDENCE_PERMIT - UTILITY_BILL - BANK_STATEMENT - RENTAL_AGREEMENT - TAX_DOCUMENT - VOTER_REGISTRATION_CARD - BANK_REFERENCE_LETTER - LEASE_OR_TENANCY_AGREEMENT - PROOF_OF_ADDRESS countryRestrictions: DRIVERS: - USA - CAN ID_CARD: - USA - CAN RESIDENCE_PERMIT: - USA - CAN optional: {} 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````