Usage Info

This method creates a Document entity and generates a URL for secure file upload. The response includes both the document identifier and all necessary form fields to perform the POST file upload. Use this method as the first step in the document upload workflow. After receiving the URL and form values, make a POST request to the upload_url with the presign_values as form fields along with the file data. The URL includes file type enforcement and file size validation to ensure uploads match the specified parameters.

After successfully uploading the file to S3, the document record will be automatically updated with upload completion status. This method is commonly used when collecting documents from applicants, uploading supporting documentation for workflows, or attaching files to Required Documents as Fulfillments.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
subject_record_id	string	Yes	The identifier for the Subject Record with `sr_` prefix.
file_name	string	Yes	The name of the file to upload (including file extension). The extension must be one of DOCUMENT_FILE_TYPES
file_size_in_bytes	integer	Yes	The size of the file in bytes.

Example

{
  "subject_record_id": "sr_1rQYvnUQdcatd4TcZQu0l8",
  "file_name": "passport.pdf",
  "file_size_in_bytes": 1048576
}

Response

Data

Parameter	Type	Description
document	object	Object containing the created document information and upload URL details.

Document Object Parameters

Parameter	Type	Description
document_id	string	The unique identifier for the Document.
upload_url	string	The URL where the file should be uploaded via a POST request.
presign_values	object	Form fields required for POST upload to the URL. Include these as form data in the upload request.

Presign Values Parameters

Parameter	Type	Description
Content-Type	string	The MIME type of the file being uploaded (e.g., application/pdf).
X-Amz-Algorithm	string	AWS signature algorithm (AWS4-HMAC-SHA256).
X-Amz-Credential	string	AWS credentials for the presigned request.
X-Amz-Date	string	Timestamp for the presigned request in ISO 8601 format.
X-Amz-Security-Token	string	AWS security token for temporary credentials.
X-Amz-Signature	string	Signature for the presigned request to authenticate the upload.
key	string	S3 object key (path) where the file will be stored.
policy	string	Base64-encoded policy document defining upload constraints.
x-amz-meta-document-id	string	Document ID metadata that will be attached to the S3 object for tracking.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24"
  },
  "data": {
    "document": {
      "document_id": "d_1rQYvnUQdcatd4TcZQu0l8",
      "upload_url": "https://s3.amazonaws.com/bucket-name",
      "presign_values": {
        "Content-Type": "application/pdf",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "ASIAQHNPJKZEMBYT3MT4/20250925/us-east-1/s3/aws4_request",
        "X-Amz-Date": "20250925T190851Z",
        "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEMf...",
        "X-Amz-Signature": "abc123def456...",
        "key": "sr_1rQYvnUQdcatd4TcZQu0l8/d_1rQYvnUQdcatd4TcZQu0l8.pdf",
        "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wOS0yNVQyMDowODo1MVoiLCJjb25kaXRpb25zIjp...",
        "x-amz-meta-document-id": "d_1rQYvnUQdcatd4TcZQu0l8"
      }
    }
  }
}

Usage Example: Uploading to S3

Review the guide on Uploading documents via API for more information about usage.

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Invalid parameter values. Invalid file type (not in DOCUMENT_CONTENT_TYPES ).
ENTITY_NOT_FOUND	400	The `subject_record_id` provided does not exist.