openapi: 3.0.0
info:
title: Hifi Account Kyc 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: Kyc
description: Kyc endpoints
paths:
/v2/users/{userId}/kyc:
post:
summary: Update KYC information
description: 'Update the user''s KYC information.
The Update KYC endpoint allows you to add or modify the user''s existing KYC data. This is the only endpoint available for making changes to the user''s KYC information.
HIFI does not provide services to users or businesses from sanctioned and high-risk regions or unsupported US states. See [here](https://docs.hifibridge.com/docs/compliance/regions) for supported regions.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/KycUpdateBody'
responses:
'200':
$ref: '#/components/responses/KycObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: Retrieve KYC information
description: 'Get the KYC information the user currently holds.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
responses:
'200':
$ref: '#/components/responses/KycObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/requirements:
get:
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.\n\nThe 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.hifibridge.com/docs/rails/overview)). \nAdditionally, 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.\n\nThis endpoint is intended **only** for use **before** KYC submission. After submitting KYC data, use the [Retrieve KYC status](https://docs.hifibridge.com/api-reference/kyc/retrieve-kyc-status) endpoint to check the submission status and further identify any fields that may still require updates.\n"
tags:
- Kyc
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'
/v2/users/{userId}/kyc/submissions:
post:
summary: Submit KYC
description: "Submit the user's current KYC data to unlock a specific rail. Any updates to the user's KYC data prior to submission should be made using the [Update KYC](https://docs.hifibridge.com/api-reference/kyc/update-kyc-information) endpoint.) \n\nThe KYC data will only be submitted if all the required KYC fields for the rail are provided. If any required fields are missing, no submission will occur, and the user must supply the missing information using the [Update KYC](https://docs.hifibridge.com/api-reference/kyc/update-kyc-information) endpoint.\n\nA successful submission is confirmed when the response includes a KYC status object. If no such object is returned, the submission did not occur.\n\nFor more details on required and optional KYC fields for unlocking each rail, visit our [KYC Rails Requirement page](https://docs.hifibridge.com/docs/rails/overview).\nTo learn more about KYC, our KYC endpoints, and an example flow for unlocking a rail, see our [KYC Overview page](https://docs.hifibridge.com/guides/usd-rail/submit-kyb).\n"
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/RailsBody'
responses:
'200':
$ref: '#/components/responses/KycStatusSubmitResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/status:
get:
summary: Retrieve KYC status
description: "Get the user's latest KYC status for a specific rail after a KYC submission. If no KYC submission has been made for the rail, it will have an `INACTIVE` status.\n\nThe Get KYC Status endpoint provides the current KYC status of a rail, including details on any invalid or incomplete fields that may require updates. \nTo address any invalid or incomplete fields, use the [Update KYC endpoint](https://docs.hifibridge.com/api-reference/kyc/update-kyc-information), and then resubmit the data using the [Submit KYC endpoint](https://docs.hifibridge.com/api-reference/kyc/submit-kyc).\n"
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/RailsTypeOptionalParameter'
responses:
'200':
$ref: '#/components/responses/KycStatusResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/kyc/status:
get:
summary: List all KYC statuses
description: 'List all KYC statuses based on the provided filters.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdOptionalParameter'
- $ref: '#/components/parameters/UserNameParameter'
- $ref: '#/components/parameters/UserEmailV2Parameter'
- $ref: '#/components/parameters/RailsTypeOptionalParameter'
- $ref: '#/components/parameters/KycStatusArrayOptionalParameter'
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/CreatedBeforeParameter'
- $ref: '#/components/parameters/CreatedAfterParameter'
responses:
'200':
$ref: '#/components/responses/AllKycStatusesResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/kyc-link:
post:
summary: Generate a KYC link
description: 'Generate a KYC link to create a user, unlock rails for a user, or submit KYC for a user.
This endpoint allows you to generate a HIFI-hosted KYC link that can be shared with users to collect their KYC information. The collected data can be used for User Creation, KYC Submission, or unlocking KYC rails for the user.
'
tags:
- Kyc
requestBody:
$ref: '#/components/requestBodies/KycLinkBody'
responses:
'200':
$ref: '#/components/responses/KycLinkResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/ubos:
post:
summary: Add a UBO
description: 'Add a UBO to the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/AddUboBody'
responses:
'200':
$ref: '#/components/responses/UboObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: List all UBOs
description: 'Get all UBOs associated with the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
responses:
'200':
$ref: '#/components/responses/UboObjectAllRecordsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/ubos/{uboId}:
post:
summary: Update a UBO
description: 'Update a UBO for the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/UboIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/UpdateUboBody'
responses:
'200':
$ref: '#/components/responses/UboObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: Retrieve a UBO
description: 'Get a specific UBO associated with the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/UboIdPathParameter'
responses:
'200':
$ref: '#/components/responses/UboObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/documents:
post:
summary: Add documents
description: 'Add documents to the user''s KYC.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/AddDocumentBody'
responses:
'200':
$ref: '#/components/responses/DocumentObjectAllRecordsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: List all documents
description: 'Get all documents associated with the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
responses:
'200':
$ref: '#/components/responses/DocumentObjectAllRecordsResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
/v2/users/{userId}/kyc/documents/{documentId}:
post:
summary: Update a document
description: 'Update a document for the user.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/DocumentIdPathParameter'
requestBody:
$ref: '#/components/requestBodies/UpdateDocumentBody'
responses:
'200':
$ref: '#/components/responses/DocumentObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
get:
summary: Retrieve a document
description: 'Get a specific document associated with the user or ubo.
'
tags:
- Kyc
parameters:
- $ref: '#/components/parameters/UserIdPathParameter'
- $ref: '#/components/parameters/DocumentIdPathParameter'
responses:
'200':
$ref: '#/components/responses/DocumentObjectResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
components:
schemas:
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
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
KycBusinessObject:
type: object
title: KYC Object (Business)
properties:
userId:
type: string
format: uuid
kycInfo:
type: object
properties:
type:
type: string
enum:
- business
businessName:
type: string
businessNameLocal:
type: string
alternativeNames:
type: array
items:
type: string
businessDescription:
type: string
email:
type: string
format: email
phone:
type: string
sourceOfFunds:
type: string
businessType:
type: string
businessIndustry:
type: string
website:
type: string
address:
type: object
$ref: '#/components/schemas/Address'
registeredAddress:
type: object
$ref: '#/components/schemas/Address'
postalAddress:
type: object
$ref: '#/components/schemas/Address'
taxIdentificationNumberType:
type: string
taxIdentificationNumber:
type: string
leiNumber:
type: string
daoStatus:
type: boolean
transmitsCustomerFunds:
type: boolean
formationDate:
type: string
ipAddress:
type: string
format: ipv4
formationDocUrl:
type: string
proofOfOwnershipUrl:
type: string
complianceScreeningExplanation:
type: string
ultimateBeneficialOwners:
type: array
items:
$ref: '#/components/schemas/UboObject'
proofOfAddressType:
type: string
proofOfAddressUrl:
type: string
certificateOfRegistrationDocType:
type: string
certificateOfRegistrationDocUrl:
type: string
certificateNumber:
type: string
businessRegistrationDocUrl:
type: string
registrationNumber:
type: string
licenseExpirationDate:
type: string
certificateOfIncorporationDocUrl:
type: string
incorporationNumber:
type: string
incorporationDate:
type: string
incorporationCountry:
type: string
incorporationState:
type: string
controlScheme:
type: string
shareStructureUrl:
type: string
constitutionOrAnnualReportUrl:
type: string
articlesOfAssociationUrl:
type: string
uboDeclarationUrl:
type: string
partnershipMinsOfMeetingUrl:
type: string
partnershipDeedUrl:
type: string
certificateOfIncumbencyUrl:
type: string
sourceOfFundsUrl:
type: string
organizationStructureUrl:
type: string
flowOfFundsUrl:
type: string
purpose:
type: string
productServiceCategory:
type: string
tradeName:
type: string
exportCountry:
type: string
tradeType:
type: string
sofEuQuestionnaire:
type: object
$ref: '#/components/schemas/SofEuKybQuestionnaire'
supplementaryInfo:
type: string
supplementaryUrl:
type: string
documents:
type: array
items:
$ref: '#/components/schemas/DocumentObject'
IndividualKycUpdate:
type: object
title: Update Individual User KYC
properties:
firstName:
type: string
firstNameLocal:
type: string
description: first name in local language.
middleName:
type: string
middleNameLocal:
type: string
description: middle name in local language.
lastName:
type: string
lastNameLocal:
type: string
description: last name in local language.
nationality:
type: string
description: Three-letter alpha-3 country code as defined in the ISO 3166-1 spec.
email:
type: string
description: E-mail address for compliance-related communications.
format: email
phone:
type: string
description: Phone number in E.164 format "+12223334444".
address:
type: object
description: Address of the user.
$ref: '#/components/schemas/Address'
dateOfBirth:
type: string
format: date
description: Date of birth in format yyyy-mm-dd.
countryOfBirth:
type: string
description: Three-letter alpha-3 country code as defined in the ISO 3166-1 spec.
stateOfBirth:
type: string
description: The state, region, district, county or another territorial entity of birth inside a country, if applicable.
placeOfBirth:
type: string
description: User place of birth. This can be a city, a town or another settlement type.
gender:
type: string
enum:
- M
- F
country:
type: string
description: "User country. This is usually a country of the last uploaded ID document, and it may differ from the country of birth. \nThree-letter alpha-3 country code as defined in the ISO 3166-1 spec.\n"
taxIdentificationNumber:
type: string
description: "Taxpayer identification number that is unique to each taxpayer.\nFor individual US customers, SSN should be used. \nFor business US customers, EIN should be used.\n"
taxResidenceCountry:
type: string
description: Three-letter alpha-3 country code as defined in the ISO 3166-1 spec.
ipAddress:
type: string
description: "IP address of the user. \n\n(See [here](https://docs.hifibridge.com/docs/compliance/regions) for the list of unsupported countries/states.)\n"
format: ipv4
govIdType:
type: string
enum:
- PASSPORT
- ID_CARD
- DRIVERS
govIdFrontUrl:
type: string
description: 'URL or Base64 encoded string of the front of the user''s government issued ID.
*Maximum file size 3MB and minimum file size 10KB
*If the file is base64 encoded, it must start with "data:"
*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
'
govIdBackUrl:
type: string
description: 'URL or Base64 encoded string of the back of the user''s government issued ID.
*Maximum file size 3MB and minimum file size 10KB
*If the file is base64 encoded, it must start with "data:"
*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
'
govIdCountry:
type: string
description: 'Alpha-3 country code of the provided government id as defined in the ISO 3166-1 spec. Note that the government ID may be different from the ''country'' above.
'
govIdNumber:
type: string
govIdIssuanceDate:
type: string
format: date
description: The issue date of the Gov ID document in format yyyy-mm-dd.
govIdExpirationDate:
type: string
format: date
description: 'The expiry date of the Gov ID document in format yyyy-mm-dd.
'
govIdIssuanceAuthority:
type: string
description: Issuing authority of the Gov ID document.
govIdHandHoldUrl:
type: string
description: 'URL or Base64 encoded string of image of the user holding their government issued ID next to their face.
*Maximum file size 3MB and minimum file size 10KB
*If the file is base64 encoded, it must start with "data:"
*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
'
proofOfAddressType:
type: string
enum:
- UTILITY_BILL
- BANK_STATEMENT
- RENTAL_AGREEMENT
- TAX_DOCUMENT
proofOfAddressUrl:
type: string
description: 'URL or Base64 encoded string of the file of the proof of address.
(See [here](https://docs.hifibridge.com/docs/compliance/regions) for the list of unsupported countries/states.)
*Maximum file size 3MB and minimum file size 10KB
*If the file is base64 encoded, it must start with "data:"
*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
'
sofEuQuestionnaire:
type: object
title: Source of Funds and Expected Use Questionnaire
description: Source of Funds and Expected Use Questionnaire
$ref: '#/components/schemas/SofEuKycQuestionnaire'
idType:
type: string
enum:
- PASSPORT
- ID_CARD
- DRIVERS
- NIN
idNumber:
type: string
additionalIdType:
type: string
description: 'Required only for "AFRICA_NIGERIA" rail and must be "BVN" type:
'
additionalIdNumber:
type: string
description: 'Required only for "AFRICA_NIGERIA" rail and must be the BVN number.
'
purpose:
type: array
description: "The purposes for unlocking this rail. Multiple values can be put into an array. Only required for `MULTI_CURRENCY_ACCOUNT` rail. \n\nLook up the purpose code [here](https://docs.hifibridge.com/docs/compliance/references/account-purposes).\n"
productServiceCategory:
type: string
description: 'The category of the product or service the user is in. Only required for `MULTI_CURRENCY_ACCOUNT` rail.
Look up the product and service category code [here](https://docs.hifibridge.com/docs/compliance/references/product-service-categories).
'
supplementaryInfo:
type: string
description: 'This field allows the inclusion of additional textual information or context that may be relevant to the KYC process.
'
supplementaryUrl:
type: string
description: 'This field is designed to contain supplementary documents or files that can be uploaded as part of the KYC process.
URL or Base64 encoded string of the file of the supplementary information.
*Maximum file size 3MB and minimum file size 10KB
*If the file is base64 encoded, it must start with "data:"
*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
'
DocumentObject:
type: object
title: Document Object
properties:
type:
type: string
subType:
type: string
issuedCountry:
type: string
issuedDate:
type: string
format: date
expiryDate:
type: string
format: date
number:
type: string
description:
type: string
url:
type: string
deprecated: true
fileId:
type: string
uboId:
type: string
ReviewResultObject:
type: object
title: Review Result
properties:
reviewAnswer:
type: string
enum:
- APPROVED
- DECLINED
reviewRejectType:
type: string
enum:
- FINAL
- RETRY
rejectReasons:
type: array
items:
type: string
comment:
type: string
KycLinkForUnlockingRails:
type: object
title: KYC Link for Unlocking Rails
required:
- userId
- rails
properties:
userId:
type: string
rails:
type: array
items:
type: string
enum:
- USD
- SOUTH_AMERICA_STANDARD
- AFRICA_GENERAL
- AFRICA_NIGERIA
description: KYC rails to unlock for the user
redirectUrl:
type: string
description: URL to redirect to after KYC information is submitted, userId will be appended to the URL as a query parameter
recipientEmail:
type: string
description: Email address to send the KYC link to if provided (only in production)
templateId:
type: string
description: Template ID to use for the KYC link, please contact HIFI for more information
GlobalNetworkRailKycSubmissionObject:
type: object
title: Kyc Submission Object (GLOBAL_NETWORK)
properties:
GLOBAL_NETWORK:
type: object
properties:
status:
$ref: '#/components/schemas/KycStatusEnum'
warnings:
type: array
message:
type: string
onRamp:
type: object
additionalProperties: false
offRamp:
type: object
additionalProperties: false
properties:
brl:
type: object
properties:
pix:
$ref: '#/components/schemas/KycRailStatusObject'
hkd:
type: object
properties:
wire:
$ref: '#/components/schemas/KycRailStatusObject'
mxn:
type: object
properties:
spei:
$ref: '#/components/schemas/KycRailStatusObject'
ngn:
type: object
properties:
bank:
$ref: '#/components/schemas/KycRailStatusObject'
required:
- status
- warnings
- message
- onRamp
- offRamp
required:
- GLOBAL_NETWORK
Rails:
type: object
properties:
rails:
$ref: '#/components/schemas/RailsEnum'
required:
- rails
InternalServerError:
type: object
properties:
error:
type: string
example: Unexpected error happened
UboObject:
type: object
title: UBO Object
allOf:
- $ref: '#/components/schemas/UboAdd'
VerificationStatusObject:
type: object
title: Verification Status
properties:
reviewResult:
$ref: '#/components/schemas/ReviewResultObject'
UsdRailBusinessKycStatusObject:
type: object
title: Kyc Status Object (USD - Business)
properties:
status:
$ref: '#/components/schemas/KycStatusEnum'
message:
type: string
reviewResult:
$ref: '#/components/schemas/ReviewResultObject'
details:
$ref: '#/components/schemas/ReviewDetailsBusinessObject'
required:
- status
- message
- reviewResult
- details
RailsEnum:
type: string
description: The type of rail.
enum:
- USD
- SOUTH_AMERICA_STANDARD
- AFRICA_GENERAL
- AFRICA_NIGERIA
- GLOBAL_NETWORK
ReviewDetailsIndividualObject:
type: object
title: Review Details Individual
properties:
personalInfo:
$ref: '#/components/schemas/Verificati
# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hifi/refs/heads/main/openapi/hifi-kyc-api-openapi.yml