Use the KYC Status endpoint to check where a user’s verification stands, diagnose issues, and confirm when they’re ready to use a rail.
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:
Current KYC application status
Human-readable context for developers
Detailed screening outcome from the compliance engine
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:
Screening outcome: APPROVED or DECLINED
Resubmission permission: RETRY (can resubmit) or FINAL (hard rejection). Only present when reviewAnswer is DECLINED.
Enumerated rejection reasons. Only present when reviewAnswer is DECLINED.
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.
Non-document information: name, address, date of birth, tax ID Outcome of the compliance checks for the submitted personal information.
Government ID documentation review results Aggregate decision for all identity documents.
Uploaded identity documents that were reviewed. UUID for the document uploaded through Update KYC.
Document category such as PASSPORT or ID_CARD.
Optional qualifier like FRONT_SIDE or BACK_SIDE.
Decision for the individual document, including remediation guidance when declined.
Proof of address documentation (if submitted) Final decision for the proof-of-address submission.
Proof-of-address documents under review. UUID for the document uploaded through Update KYC.
Document category such as UTILITY_BILL or BANK_STATEMENT.
Qualifier like SINGLE_SIDE when applicable.
Outcome for that document, including decline feedback.
Source of funds and intended use responses Status of the compliance questionnaire evaluation.
Response Breakdown ACTIVE
INACTIVE
PENDING
MANUAL_REVIEW
INCOMPLETE
RFI_PENDING
REJECTED
CONTACT_SUPPORT
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 Update Document Add Document
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" : {} }
