Company Review Document Requests
Identify which documents are needed to complete the Company Review process
During the Company Review process, a number of scenarios require Check to request for documentation from the company. When these situations arise, the required documentation will be surfaced via the Requirements API, along with the document options that fulfill the request.
This workflow couples well with Uploading Company Provided Documents to enable the end-user to upload a document directly to Check in order to supply the requested information.
Example flow for Signatory Identity Verification
Check determines that signatory identity verification is required to move forward in Company Review.
A webhook of event type created for the Requirement topic will be issued for this new documentation request. This can also be proactively retrieved by calling the List requirements endpoint.
{
"event": "created",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "signatory_identity_verification",
"categories": ["company_provided_documents"],
"status": "not_provided",
"errors": [],
"guidance": {
"document_options": [
{
"name": "signatory_photo_id",
"label": "Non-expired government-issued photo ID for authorized signer",
}
],
"accepted_file_formats": [
"application/pdf",
"image/jpeg",
"image/png",
]
}
}
}
The document is collected from the end-user and sent to Check with the two-step document upload flow.
Step 1: Create a company provided document
In your user interface, it is recommended that you populate a dropdown of document options from the guidance.document_options list. The user should select which document they would like to upload to fulfill the requirement. This document_type is sent to Check when creating the company provided document resource.
curl --request POST \
--url https://sandbox.checkhq.com/company_provided_documents \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
> --data '{"company": "com_kGYEICK22GEzj8trreH3", "document_type": "signatory_photo_id"}'
When this request succeeds, the response includes the upload_url, which is the Check API URL. This will be used to upload the actual file associated with this document.
{
"id": "doc_1fyTzNTwEg1gWwKOqYK9",
"company": "com_kGYEICK22GEzj8trreH3",
"document_type": "signatory_photo_id",
"upload_url": "https://sandbox.checkhq.com/company_provided_documents/doc_1fyTzNTwEg1gWwKOqYK9/upload",
"upload_status": "pending",
"file_content_type": null,
"provided_filename": null
}
Step 2: Upload a file for the company provided document
With the company provided document object created, we need to upload the actual file associated with the document. To do this, we make a PUT request to the upload_url returned in the above response. This request is a multipart/form-data request with a single parameter file containing the file contents.
curl --request PUT \
--url https://sandbox.checkhq.com/company_provided_documents/doc_1fyTzNTwEg1gWwKOqYK9/upload \
--header 'Authorization: Bearer YOUR_API_KEY' \
> --form 'file=@"/path/to/file/test.pdf"'
The file has been uploaded successfully as indicated by the upload_status in the response.
{
"id": "doc_1fyTzNTwEg1gWwKOqYK9",
"company": "com_kGYEICK22GEzj8trreH3",
"document_type": "940",
"upload_url": "https://sandbox.checkhq.com/company_provided_documents/doc_1fyTzNTwEg1gWwKOqYK9/upload",
"upload_status": "uploaded",
"file_content_type": "application/pdf",
"provided_filename": "test.pdf"
}
Upon successful upload, the requirement will be automatically transitioned to the status pending_verification. This status update will issue a webhook with the Requirements topic. The pending_verification status indicates that the Check team will review the provided documentation.
{
"event": "updated",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "signatory_identity_verification",
"categories": ["company_provided_documents"],
"status": "pending_verification",
"errors": [],
"guidance": {
"document_options": [
{
"name": "signatory_photo_id",
"label": "Non-expired government-issued photo ID for authorized signer",
}
]
}
}
}
The Requirement will be fulfilled once the Check team successfully processes the document and approves it. The status will be transitioned from pending_verification to completed and another updated webhook with a Requirements topic will be emitted.
{
"event": "updated",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "signatory_identity_verification",
"categories": ["company_provided_documents"],
"status": "completed",
"errors": [],
"guidance": {
"document_options": [
{
"name": "signatory_photo_id",
"label": "Non-expired government-issued photo ID for authorized signer",
}
]
}
}
}
In some cases, Check's review of the document will find issues that prevent the provided documentation from fulfilling the requirement. In these scenarios, the requirement will transition to document_rejected and errors will be added to indicate what the problem was. The user should upload a new document without these errors to fulfill the requirement.
{
"event": "updated",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "signatory_identity_verification",
"categories": ["company_provided_documents"],
"status": "document_rejected",
"errors": [
{
"type": "provided_document_signatory_name_missing",
"label": "Provided document must include name of signatory",
"description": null
},
{
"type": "provided_document_expired",
"label": "Provided document must not be expired",
"description": "Document expired on Aug 4, 2020."
// This description field is optional and provided by the Check Risk Ops team
// to provide more context. It should not be automatically displayed to the
// end-user, but could be helpful for your Support team in fielding questions.
}
],
"guidance": {
"document_options": [
{
"name": "signatory_photo_id",
"label": "Non-expired government-issued photo ID for authorized signer",
}
]
}
}
}
Example flow for Federal EIN Verification
Federal EIN verification is a special type of Company Review documentation request, that works well when used alongside the Automatic Federal EIN Verification endpoint.
The workflow is very similar to the one detailed above with a few notable differences.
Whenever Check has both a legal name and Federal EIN for a company, we will automatically begin verifying whether those values have been entered correctly. When we are not able to verify these values against one another, the federal_ein_verification object will have a status of rejected.
When this happens, a documentation request will be surfaced in the Requirements API, issuing a webhook notification.
{
"event": "created",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "federal_ein_verification",
"categories": ["company_provided_documents"],
"status": "not_provided",
"errors": [],
"guidance": {
"document_options": [
{
"name": "ss4",
"label": "IRS Form SS4",
},
{
"name": "cp_575",
"label": "IRS Form CP_575",
},
{
"name": "147_C",
"label": "IRS Form 147-C",
},
{
"name": "940",
"label": "IRS Form 940",
},
{
"name": "941",
"label": "IRS Form 941",
},
{
"name": "943",
"label": "IRS Form 943",
},
{
"name": "944",
"label": "IRS Form 944",
},
{
"name": "945",
"label": "IRS Form 945",
},
],
"accepted_file_formats": [
"application/pdf",
"image/jpeg",
"image/png",
]
}
}
}
Check supports exactly three (3) attempts to verify a company legal name and FEIN. After the third attempt, if the final verification is still rejected, the status will show as final_rejected to indicate that no further attempts to automatically verify FEIN will be attempted. In this scenario, fulfilling the documentation request is the only option available to move forward in enrollment.
If the user fixes their legal name and/or FEIN before that final attempt and we are able to verify the updated information, the Federal EIN verification will have status verified and the documentation will no longer be needed. This will issue a webhook of event type deleted to the Requirements topic.
{
"event": "deleted",
"data": {
"id": "req_123",
"company": "com_kGYEICK22GEzj8trreH3",
"requirement": "federal_ein_verification",
"categories": ["company_provided_documents"],
"status": "not_provided",
"errors": [],
"guidance": {
"document_options": [
{
"name": "ss4",
"label": "IRS Form SS4",
},
{
"name": "cp_575",
"label": "IRS Form CP_575",
},
{
"name": "147_C",
"label": "IRS Form 147-C",
},
{
"name": "940",
"label": "IRS Form 940",
},
{
"name": "941",
"label": "IRS Form 941",
},
{
"name": "943",
"label": "IRS Form 943",
},
{
"name": "944",
"label": "IRS Form 944",
},
{
"name": "945",
"label": "IRS Form 945",
},
]
"accepted_file_formats": [
"application/pdf",
"image/jpeg",
"image/png",
]
}
}
}
Updated over 1 year ago