HIFI Docs

This guide focuses on the USD rail. Requirements and response structure differ for other rails—see the API Reference for complete details.

Status Overview

Status	Description
INACTIVE	No KYC submitted yet—call Submit KYC to begin verification
INCOMPLETE	Submitted data needs updates—fix flagged items and resubmit
PENDING	KYC submitted and is moving through automated compliance checks or bank onboarding
MANUAL_REVIEW	Compliance team manually reviewing before final decision
RFI_PENDING	Compliance requested additional information—check your compliance email
ACTIVE	User passed compliance review and can use the USD rail
REJECTED	Permanently denied for USD rail—resubmission not permitted
CONTACT_SUPPORT	System couldn’t confirm status—contact HIFI support

Contact support if an applicant remains in PENDING or MANUAL_REVIEW for more than 24 hours.

Response Structure

Top-Level Fields

The KYC status response contains four top-level fields:

string

Current KYC application status

string

Human-readable context for developers

object

Detailed screening outcome from the compliance engine

object

Breakdown of compliance categories and review results

Review Result

Each compliance category includes a reviewResult object with a general summary of the compliance review outcome:

string

Screening outcome: APPROVED or DECLINED

string

Resubmission permission: RETRY (can resubmit) or FINAL (hard rejection). Only present when reviewAnswer is DECLINED.

array[string]

Enumerated rejection reasons. Only present when reviewAnswer is DECLINED.

string

Human-readable explanation of the rejection. Only present when reviewAnswer is DECLINED.

Review Details

The details object returns the compliance review outcome for each KYC category. Every category includes a reviewResult, and documentation-based categories also expose the individual files that were reviewed.

object

Non-document information: name, address, date of birth, tax ID

Show properties

ReviewResultObject

Outcome of the compliance checks for the submitted personal information.

object

Government ID documentation review results

Show properties

ReviewResultObject

Aggregate decision for all identity documents.

array[Document]

Uploaded identity documents that were reviewed.

Show Document item

string

UUID for the document uploaded through Update KYC.

string

Document category such as PASSPORT or ID_CARD.

string

Optional qualifier like FRONT_SIDE or BACK_SIDE.

ReviewResultObject

Decision for the individual document, including remediation guidance when declined.

object

Proof of address documentation (if submitted)

Show properties

ReviewResultObject

Final decision for the proof-of-address submission.

array[Document]

Proof-of-address documents under review.

Show Document item

string

UUID for the document uploaded through Update KYC.

string

Document category such as UTILITY_BILL or BANK_STATEMENT.

string

Qualifier like SINGLE_SIDE when applicable.

ReviewResultObject

Outcome for that document, including decline feedback.

object

Source of funds and intended use responses

Show properties

ReviewResultObject

Status of the compliance questionnaire evaluation.

Response Breakdown

User passed all compliance checks and completed bank onboarding. They can now use the USD rail.

{
  "status": "ACTIVE",
  "message": "",
  "reviewResult": {
    "reviewAnswer": "APPROVED",
    "reviewRejectType": "",
    "rejectReasons": [],
    "comment": ""
  },
  "details": {
    "identity": {
      "reviewResult": {
        "reviewAnswer": "APPROVED",
        "reviewRejectType": "",
        "rejectReasons": [],
        "comment": ""
      },
      "details": [
        {
          "id": "989c9fae-9846-48e0-a5c1-2035e9cbd323",
          "type": "ID_CARD",
          "subType": "FRONT_SIDE",
          "reviewResult": {
            "reviewAnswer": "APPROVED",
            "reviewRejectType": "",
            "rejectReasons": [],
            "comment": ""
          }
        }
      ]
    },
    "questionnaire": {
      "reviewResult": {
        "reviewAnswer": "APPROVED",
        "reviewRejectType": "",
        "rejectReasons": [],
        "comment": ""
      },
      "details": []
    },
    "personalInfo": {
      "reviewResult": {
        "reviewAnswer": "APPROVED",
        "reviewRejectType": "",
        "rejectReasons": [],
        "comment": ""
      },
      "details": []
    }
  }
}

No KYC submission made yet. Call the Submit KYC endpoint to begin verification.

{
  "status": "INACTIVE",
  "message": "The rail is not active.",
  "reviewResult": {},
  "details": {}
}

Application is moving through automated compliance screening or bank onboarding.

    {
        "status": "PENDING",
        "message": "",
        "reviewResult": {},
        "details": {
            "identity": {
                "reviewResult": {},
                "details": [...]
            },
            "questionnaire": {
                "reviewResult": {}
            },
            "personalInfo": {
                "reviewResult": {}
            }
        }
    }

Contact support if status doesn’t change within 24 hours for individual applicants.

Compliance team is manually reviewing the application. This typically follows PENDING when additional investigation is needed.

{
  "status": "MANUAL_REVIEW",
  "message": "",
  "reviewResult": {},
  "details": {}
}

Contact support if status doesn’t change within 24 hours.

Submitted data needs updates before verification can continue. Use the reviewResult in each compliance category to identify what needs fixing.

{
  "status": "INCOMPLETE",
  "message": "",
  "reviewResult": {
    "reviewAnswer": "DECLINED",
    "reviewRejectType": "RETRY",
    "rejectReasons": ["BAD_PROOF_OF_IDENTITY"],
    "comment": ""
  },
  "details": {
    "identity": {
      "reviewResult": {
        "reviewAnswer": "DECLINED",
        "reviewRejectType": "RETRY",
        "rejectReasons": [],
        "comment": "The uploaded document is not acceptable or no longer valid. Upload a different document."
      },
      "details": [
        {
          "id": "42e54f82-dd1d-4cdf-844c-fd56fcfcdb8e",
          "type": "ID_CARD",
          "subType": "BACK_SIDE",
          "reviewResult": {
            "reviewAnswer": "DECLINED",
            "reviewRejectType": "RETRY",
            "rejectReasons": ["BAD_PROOF_OF_IDENTITY"],
            "comment": "The uploaded document is not acceptable or no longer valid. Upload a different document."
          }
        }
      ]
    },
    "questionnaire": {
      "reviewResult": {
        "reviewAnswer": "APPROVED",
        "reviewRejectType": "",
        "rejectReasons": [],
        "comment": ""
      }
    },
    "personalInfo": {
      "reviewResult": {
        "reviewAnswer": "APPROVED",
        "reviewRejectType": "",
        "rejectReasons": [],
        "comment": ""
      }
    }
  }
}

How to resolve:

Check the reviewResult in each compliance category for DECLINED items
Read the comment field for specific guidance
Use Update KYC to update non-document information, or Update Document** / **Add Document to update documentation.
Call Submit KYC to trigger a new review

Compliance category mapping:

Category	Contains
identity	Government ID documentation
questionnaire	Source of funds and intended use responses
personalInfo	Name, address, date of birth, tax ID
proofOfAddress	Proof of address documentation (if provided)

For compliance reasons, detailed rejection information is only available for documentation—not for other categories.

Compliance sent a Request for Information (RFI) to your compliance email asking for additional details about this user.

{
  "status": "RFI_PENDING",
  "message": "",
  "reviewResult": {},
  "details": {}
}

Monitor your compliance inbox for RFI requests from @hifi.com

User is permanently denied for the USD rail. Resubmission via API is not permitted.

{
  "status": "REJECTED",
  "message": "",
  "reviewResult": {},
  "details": {}
}

Contact support if you believe this status is incorrect.

System couldn’t process the KYC or return the correct status. Contact HIFI support for resolution.

{
  "status": "CONTACT_SUPPORT",
  "message": "",
  "reviewResult": {},
  "details": {}
}

Introduction

Core concepts

Features

Compliance

Payments

References

KYC Status

Status Overview

Response Structure

Top-Level Fields

Review Result

Review Details

Response Breakdown