Uploading Company Provided Documents

Learn how to upload company provided documents to Check API

📘

Alpha Feature

This feature is currently under a feature flag and is in an alpha-release stage. Please contact us if you would like it enabled.

The company provided document object represents a company document uploaded directly to Check API. This has implications in the business verification process, where a company may be asked for additional documentation to fulfill a verification requirement. A company provided document must be a PDF, JPG, or PNG and cannot exceed 6 MB in size.

The following document types are supported:

  • 940 Form (940)
  • SS4 (ss4)
  • Driver's License (drivers_license)
  • Voided Check (voided_check)
  • Bank Statement (bank_statement)
  • Bank Letter (bank_letter)

Document Upload Example

Step 1: Create a company provided document

To upload a document to Check API, begin by first creating a company provided document object.

The following example creates a document which represents a 940 form for a company.

We make a POST request to http://sandbox.checkhq.com/company_provided_documents with the ID of the company we are uploading the document for and the type of the document.

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": "940"}'

When this request succeeds, we are met with some metadata related to the created entity. The key attributes to note are the upload_url, upload_status, and file_content_type. The upload_url is the Check API URL which we will later make a multipart/form-data request to when uploading the actual file associated with this document. The upload_status represents whether this document has been uploaded or not. All company provided documents have an upload_status of "pending" upon initial creation, as they do not yet have an associated uploaded file. The file_content_type is the MIME type of the uploaded file. This is null by default.

{
    "id": "doc_1fyTzNTwEg1gWwKOqYK9",
    "company": "com_kGYEICK22GEzj8trreH3",
    "document_type": "940",
    "upload_url": "https://sandbox.checkhq.com/company_provided_documents/doc_1fyTzNTwEg1gWwKOqYK9/upload",
    "upload_status": "pending",
    "file_content_type": 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. The path parameter com_kGYEICK22GEzj8trreH3 is the ID of the company we created a document for above. This request is a multipart/form-data request, with the form data containing a single key file whose value is the file we are uploading.

curl --request PUT \
     --url https://sandbox.checkhq.com/company_provided_documents/doc_1fyTzNTwEg1gWwKOqYK9/upload \
     --header 'Authorization: Bearer YOUR_API_KEY' \
>    --form '[email protected]"/path/to/file/test.pdf"'

Upon successful upload, we receive the metadata for the company provided document we created previously, this time with an upload_status of "uploaded" and a file_content_type which denotes the MIME type of the uploaded file, in this case "application/pdf".

{
    "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"
}

Upload Errors

Uploaded files must be PDF, JPG, or PNG and be less than 6 MB in size. The upload endpoint will surface a validation error when the user does not attach a file to the request or when the user attempts to upload a file which does not meet the above criteria.

Example error response for a request sent with no file in the request body

{
    "error": {
        "type": "validation_error",
        "message": "Please correct the required fields and try again.",
        "input_errors": [
            {
                "message": "File must be provided"
            }
        ]
    }
}

Example error response for a request sent with a file larger than 6 MB

HTTP content length exceeded 10485760 bytes.

Example error response for a request sent with a file that is not one of the supported file types

{
    "error": {
        "type": "validation_error",
        "message": "Please correct the required fields and try again.",
        "input_errors": [
            {
                "message": "Invalid file type. File must be application/pdf, image/jpeg, or image/png"
            }
        ]
    }
}

Did this page help you?