Documents Upload

The Documents Upload API allows you to upload files and documents that will be used in form submissions. This is often a prerequisite step before submitting answers that require document references.

API Endpoint

POST {base_url}/ExtForm/submissions/{submissionId}/documents

Request Format

This endpoint accepts a multipart/form-data request containing one or more documents.

Path Parameters

Parameter	Type	Required	Description
submissionId	string	Yes	ID of the submission these documents belong to

Request Headers

Content-Type: multipart/form-data
Authorization: Bearer {token}

Request Parameters

Each document in the request must include the following fields:

Parameter	Type	Required	Description
OriginalFileName	string	Yes	Original name of the file as it appears on the user's system
FileContent	file	Yes	The file to upload. Set this field to the actual file content in your multipart/form-data request
DocumentTypeId	string	No	Type of document (refer to the Document Types Reference for valid values)
Description	string	No	Description of the document
ExpiryDate	date	No	Expiry date of the document (if applicable) in YYYY-MM-DD format

Document Types

The DocumentTypeId parameter should be set to one of the document types listed in the Document Types Reference. This reference provides a comprehensive list of all supported document types organized by categories:

• Identity Documents - Such as Passport, IdCardFront, IdCardBack, Liveness
• Financial Documents - Such as SourceOfFunds, SourceOfWealth, FinancialStatements
• Tax Documents - Such as W8BEN, W9, CrsDocument
• Corporate Documents - Such as CompanyLicense, ConstitutionalDocument, EvidenceOfOwnerShip
• Agreements & Forms - Such as ClientAgreement, SubscriptionAgreement
• Compliance Documents - Such as ProofofAddress, ClientRiskAssessment
• Other Documents - For documents that don't fit in the above categories

Selecting the appropriate document type is crucial for proper document processing and validation. For example:

• Documents marked with MRZ Code support (like Passport and IdCardFront) will undergo automated data extraction
• Identity documents may trigger specific verification workflows
• Different document types may have different validation requirements

Response Format

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": [
    {
      "id": "d8f72bae-5c9a-4f8e-b8e7-19d8fcd7e34b",
      "fileName": "baf5901b-51b6-4b55-bb94-9b0f67bb833d_passport_scan.jpg",
      "originalFileName": "passport_scan.jpg",
      "description": "",
      "documentTypeId": "Passport"
    }
  ]
}

Response Fields

Field	Description
id	Unique identifier for the uploaded document (used in form answer submissions)
fileName	System-generated name of the file (includes GUID prefix)
originalFileName	Original name of the file as uploaded
description	Description of the document (if provided)
documentTypeId	Type of document (if provided)

Example Usage

cURL Example

curl -X POST \
  {base_url}/ExtForm/submissions/7ac9ab5e-4123-4456-b8c3-123456789012/documents \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: multipart/form-data' \
  -F 'documents[0].OriginalFileName=passport.jpg' \
  -F 'documents[0].DocumentTypeId=Passport' \
  -F 'documents[0].FileContent=@/path/to/passport.jpg'

Multiple Document Upload Example

curl -X POST \
  {base_url}/ExtForm/submissions/7ac9ab5e-4123-4456-b8c3-123456789012/documents \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: multipart/form-data' \
  -F 'documents[0].OriginalFileName=passport.jpg' \
  -F 'documents[0].DocumentTypeId=Passport' \
  -F 'documents[0].FileContent=@/path/to/passport.jpg' \
  -F 'documents[1].OriginalFileName=proof_of_address.pdf' \
  -F 'documents[1].DocumentTypeId=ProofofAddress' \
  -F 'documents[1].FileContent=@/path/to/proof_of_address.pdf'

Error Handling

Status Code	Description	Solution
400	"At least one document is required"	Ensure you're including at least one document in the request
400	Invalid request parameters	Check file name and other parameters
400	File size exceeded	Ensure file is under the maximum size limit
400	Unsupported file format	Check that the file format is supported
400	Invalid document type	Verify that the DocumentTypeId is one of the values listed in the Document Types Reference
401	Unauthorized	Verify your authentication token
404	Submission not found	Verify the submission ID exists
500	Internal server error	Contact support with the error details

Document Processing

After upload, certain document types undergo automated processing:

• Identity Documents (Passport, IdCardFront): OCR processing extracts identity information
• Liveness Images: Compared with identity document photos for verification
• Some documents may trigger additional verification workflows based on their type

Important Notes

1. Document IDs returned from this API are essential for completing form submissions that require document references.
2. For documents with expiry dates (like passports and ID cards), include the ExpiryDate parameter.
3. Documents with MRZ code support undergo OCR processing to extract information automatically.
4. Always select the appropriate document type from the Document Types Reference to ensure proper processing.

Using Document IDs in Form Submissions

After successful upload, you'll receive document IDs that should be referenced in your form submissions. For example:

{
  "fqName": "PersonalInfo_Identity_Passport",
  "answer": {
    "fieldTypeId": "Passport",
    "documentId": "d8f72bae-5c9a-4f8e-b8e7-19d8fcd7e34b"
  }
}

Next Steps

After successfully uploading documents and obtaining document IDs, you can proceed to submit form answers using the Save Submission API.

Related Resources

• Get Submission Documents API - Retrieve documents for a submission
• Download Document API - Download a specific document
• Delete Documents API - Delete documents
• Document Types Reference - Comprehensive list of supported document types