Upload Files

POST/openapi/v1/files/upload

Upload document files and obtain FileIds for use when creating envelopes.

Up to 20 files per request; results are returned in the same order as the request
FileId is valid for 24 hours; expired FileIds require re-uploading
Supported formats: pdf / doc / docx / xls / xlsx / html / jpg / jpeg / png / bmp / txt
Size limits: images (jpg / jpeg / png / bmp) ≤ 10 MB; other documents ≤ 60 MB
Non-PDF source files (e.g., xlsx / docx / html) must first be converted via Create File Conversion Task before being used to create an envelope

Request Parameters

Header Parameters

AuthorizationRequiredstring

Bearer <access_token>

X-Operator-User-IdOptionalstring

Operator user ID. Not required in Authorization Code mode (the authorized user is used automatically). Optional in Client Credentials mode — omit to use the system user ID.

Request Body

application/json

FilesRequiredarray<object>

File list, minimum 1, maximum 20

⌃Sub-properties

FileNameRequiredstring

File name including extension, e.g., contract.pdf

FileBodyRequiredstring

File content, Base64 encoded. Supported formats: pdf / doc / docx / xls / xlsx / html / jpg / jpeg / png / bmp / txt. Size limits: images (jpg / jpeg / png / bmp) ≤ 10 MB; other documents ≤ 60 MB

Request Example

{
  "Files": [
    {
      "FileName": "contract.pdf",
      "FileBody": "JVBERi0xLjQK..."
    },
    {
      "FileName": "appendix.pdf",
      "FileBody": "JVBERi0xLjUK..."
    }
  ]
}

Response Parameters

Response.Data

FilesOptionalarray<object>

Upload results list, in the same order as the request Files

⌃Sub-properties

FileNameOptionalstring

Corresponding file name from the request

FileIdOptionalstring

File resource ID, valid for 24 hours, used in CreateEnvelope requests

Response Example

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "Files": [
        {
          "FileName": "contract.pdf",
          "FileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6"
        },
        {
          "FileName": "appendix.pdf",
          "FileId": "SGf7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2"
        }
      ]
    }
  }
}

Error Codes

Error Code	Description
`OPENAPI.UPLOAD_FILES_REQUIRED`	Files list is empty
`OPENAPI.UPLOAD_FILES_COUNT_EXCEEDS`	Files count exceeds the maximum limit of 20
`OPENAPI.UPLOAD_FILE_NAME_REQUIRED`	FileName is empty for one of the files
`OPENAPI.UPLOAD_FILE_BODY_REQUIRED`	FileBody is empty for one of the files
`OPENAPI.UPLOAD_FILE_EXT_UNSUPPORTED`	Unsupported file extension (only pdf/doc/docx/xls/xlsx/html/jpg/jpeg/png/bmp/txt are allowed)
`OPENAPI.UPLOAD_FILE_BASE64_INVALID`	FileBody is not a valid Base64 string
`FILE.TOO_LARGE`	File exceeds size limit (images ≤ 10MB, other documents ≤ 60MB)
`INTERNAL_ERROR`	Internal server error (storage failure, etc.)

Quick Start Create File Conversion Task