Home / Guides/ Onboard Accounts
In some cases, Applications can be flagged for review because additional Account Holder verification information is needed. This review process confirms the identity of the Person or Business and ensures compliance with Know-Your-Customer (KYC) or Know-Your-Business (KYB) regulations.
When an Application is flagged for review, it inherits the status IN_REVIEW
. Applications with an IN_REVIEW
status return one of two responses:
You can use the Application Status Event Notifications to send an email or push alerts to Account Holders to alert them of the Application review status and direct them to your document upload UI flow. In your document upload UI flow, you can use the Highnote API to generate URLs for each required document, allowing Account Holders to upload documents directly from your application or website.
Once the Account Holder has uploaded their documents, a Highnote agent reviews the documents and takes the following actions:
Documents cannot be expired, and supporting documents must be dated within 60 days. If the document appears forged, is outdated, and/or is otherwise invalid, the Application will be DENIED
.
Depending on the type of Account Holder applying for a Card Product, documentation may be required from more than one applicant. For example, if an Application is submitted for a US Business Account Holder, documents may be required for the Primary Authorized Person and each Beneficial Owner.
When an Application enters IN_REVIEW
status, the GraphQL API returns a response for why it was flagged for review. Each response contains documents that may be required to process the Application. When there are multiple response codes, the Account Holder may need to provide multiple documents.
Business entity documentation is only relevant to US Business Account Holders and includes documentation related to the business.
In cases where the US Business Account Holder is a sole proprietor, personal information can be used in place of business-related documentation. For example, a sole proprietor may not have an EIN but can have one of the following documents:
When an Application enters IN_REVIEW
status, the GraphQL API returns a response for why the Application was flagged for review. Each response contains a set of documents that may be required to process the Application. When there are multiple response codes, the Account Holder may need to provide multiple documents.
When an Application enters IN_REVIEW
status and verification documents are required, you can collect documents using two methods:
If you use the Highnote API, the document upload process consists of the following steps:
Note that one or more documents may be required based on the review response and the document type they provide.
If you are not using a server or do not have access to a server, to make requests directly from your client, you must generate a Client Token.
To start the document collection process, you must start a document upload session by generating a URL to send the Account Holder that allows them to upload their documents. You can use the Application Status Event Notifications to send an email or push alerts to Account Holders to alert them of the Application review status and provide a URL to your document uploading UI flow.
Note the following when starting a document upload session:
DENIED
if the Account Holder does not provide the required documentation within 30 days.Use the following mutation to start a document upload session. In the mutation’s response, the required documents are listed under primaryDocumentTypes
:
Document upload links expire 5 minutes after creation.
Once a document upload session has started, you must create a secure upload link for each document the applicant must upload to Highnote’s secure document store. For example, if the applicant must provide a driver’s license and utility bill, each document would need its own unique upload link.
Note the following when creating upload links:
PENDING
.uploadURL
field in the mutation's response to stream the document upload.The following types of file formats are supported for document uploads:
Type | File Formats Accepted |
---|---|
Image | .jpg , .png , .pdf |
Use the following mutation to create a document upload link. Use the DOCUMENT_UPLOAD_SESSION_ID
from the startDocumentUploadSession
response for this mutation’s variable field:
After an Account Holder has confirmed they have uploaded all required documents, you can end the document upload session.
Note the following when ending a document upload session:
SUBMITTED
.SUBMITTED
, no other actions can be taken for the session. If more documentation is required, a new session must be started to upload the additional documents.Use the following mutation to end a document upload session:
Highnote will not return a public link to access the content of the documents to best protect the Account Holder's privacy.
You can monitor the status of Account Holder documents while the Highnote team reviews them by querying for the status using the GraphQL API or the Dashboard. For a full list of application status codes, see the AccountHolderApplicationStatusCode enum.
Note the following about monitoring Application review statuses:
Use the following query to fetch the review status of an Account Holder Application:
The DATE OF BIRTH
field has a maximum age of 99 and the SSN
requires valid SSN input.
You can simulate Application reviews to ensure your UI is working and Account Holders can upload documents. When testing, you can simulate application failure under various scenarios by creating Account Holders with specific attribute values. The simulation will produce tags associated with the application decision and explain why an application outcome was APPROVED
, IN_REVIEW
, or DENIED
.
We recommend simulating scenarios that result in IN_REVIEW
or DENIED
responses for testing purposes. To simulate these responses, we recommend using the values 02/29/2000
for DOB and 111-11-1111
or 111-11-1211
for SSN.
When simulating an IN_REVIEW
or DENIED
response, you can input test values for different fields of an Application, resulting in a tag that provides context for the response and Application status. For example:
DENIED
response, you can input the value FORCE-DECLINE
for an Application's FIRST NAME
field, resulting in a NAME_MISMATCH
tag.IN_REVIEW
response, you can input the value 123 Manual Review St.
for an Application's ADDRESS LINE 1
field, resulting in an ADDRESS_MISMATCH
tag.The following table contains a list of failure values you can use to simulate an IN_REVIEW
or DENIED
response. Each failure value that returns a failure tag with an IN_REVIEW
status has a failure tag that will return the required documentation needed to approve the Application.
Field | Failure Value | Failure Tag |
---|---|---|
FIRST NAME | DECLINE | NAME_MISMATCH |
FIRST NAME | IN-REVIEW | WATCHLIST_HIT |
DATE OF BIRTH | 1900-12-12 | DOB_MISMATCH |
ADDRESS LINE 1 | 123 Decline St. | ADDRESS_MISMATCH |
ADDRESS POSTAL CODE | 66666 or 11111 | ADDRESS_MISMATCH |
PHONE NUMBER | 6666666666 | PHONE_MISMATCH |
SSN | 666-66-6666 or 111-11-1111 or 111-11-1211 | SSN_MISMATCH |
When simulating an IN_REVIEW
or DENIED
response, you can input test values for different fields of an Application, resulting in a tag that provides context for the response and Application status. For example:
DENIED
response, you can input the value FORCE-DECLINE
for an Application's BUSINESS LEGAL NAME
field, resulting in a NAME_MISMATCH
tag.IN_REVIEW
response, you can input the value 123 Manual Review St.
for an Application's BUSINESS ADDRESS LINE 1
field, resulting in an ADDRESS_MISMATCH
tag.The following table contains a list of failure values you can use to simulate an IN_REVIEW
or DENIED
response. Each failure value that returns a failure tag with an IN_REVIEW
status has a failure tag that will return the required documentation needed to approve the Application.
Field | Failure Value | Failure Tag |
---|---|---|
BUSINESS LEGAL NAME | DECLINE | BUSINESS_NAME_MISMATCH |
BUSINESS ADDRESS LINE 1 | 123 Decline St. | ADDRESS_MISMATCH |
BUSINESS ADDRESS POSTAL CODE | 66666 or 11111 | ADDRESS_MISMATCH |
EMPLOYER IDENTIFICATION NUMBER | 66-6666666 or 11-1111111 or 11-1111211 | FEIN_MISMATCH |
AUTHORIZED PERSON FIRST NAME | MISMATCH | REPRESENTATIVE_MISMATCH |
PRIMARY AUTHORIZED PERSON FIRST & GIVEN NAME | IN-REVIEW | WATCHLIST_HIT |
Business Verification Score | Passing 3 or more of the failure values above | BUSINESS_VERIFICATION_SCORE_FAILED |
Once an Application has entered IN_REVIEW
status, you can begin a document upload session to simulate adding supporting documents. Use the queries from the following sections of this guide to simulate the document upload session:
Once you've closed the document upload session, you can simulate the review status of each document by assigning a new status of APPROVED
or DENIED
. Use the following mutation to simulate the review status for each document uploaded in the upload session:
There are two scenarios where additional document upload sessions may be needed:
In the Test Environment, simulating additional document upload sessions requires the request inputs to be specific for each document type. Multiple applicants under the same Application can be selected, and multiple document types can be requested for each applicant.
Once an additional document upload session is simulated, the Application status will remain IN_REVIEW
, the currentVerification.status
for each unverified applicant will remain PENDING
, and the currentVerification.reason
for each requested applicant will be changed to DOCUMENT_UPLOAD_REQUIRED
.
An additional upload session will trigger the CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTED
notification event. The event allows you to create a unique notification template for your Account Holders when additional documents are requested for their Application.
Use the following mutation to simulate additional document upload sessions in your Test Environment:
After uploading Account Holder identity verification documents and simulating a review status for each document, you can simulate the identity verification status. The identity verification status verifies the identity of the Account Holder(s) associated with the Application. All Account Holder identities must be passed for the Application to be approved.
This simulation will transition the Application identity verification status from IN_REVIEW
to PASSED
or DENIED
. Optionally, you can simulate the status passing from IN_REVIEW
to DOCUMENT_UPLOAD_REQUIRED
if you want to test your flow for requesting additional documents.
Use the following mutation to simulate the identity verification status:
You can also simulate the outcome of an entire Application and transition the Application's status from IN_REVIEW
directly to APPROVED
or DENIED
. If multiple Account Holders are on an Application, there is only one status for the full Application.
Use the following mutation to simulate the full Application status: