Envelope Signing (eSign)API ReferenceQuery File Conversion Tasks

Query File Conversion Tasks

POST/openapi/v1/files/convert-tasks/query

Query the current status of conversion tasks in batch. Poll until a final state (success / failed / timeout).

Polling recommendation: Poll every 1–2 seconds. Most tasks reach a final state within 10 seconds.

Permission: Only tasks belonging to the current space are returned. TaskIds that do not belong to this space are silently filtered — they will not appear in the Tasks array and will not cause an error.

TaskStatus values:

ValueMeaningFinal?
pendingTask submitted, awaiting processingNo, keep polling
processingConversion in progressNo, keep polling
successConversion succeeded, ConvertedFileId is availableYes
failedConversion failed, TaskMessage contains the reasonYes
timeoutConversion timed outYes

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
TaskIdsRequiredarray<string>
Task ID list (required); up to 50 per request

Request Example

{
  "TaskIds": [
    "20260709175117139808",
    "20260709175117139809"
  ]
}

Response Parameters

Response.Data
TasksOptionalarray<object>
Task result list; unauthorized TaskIds are silently filtered and do not appear in this array
⌃Sub-properties
TaskIdOptionalstring
Task ID
TaskStatusOptionalstring
Task status: pending = submitted and awaiting processing; processing = conversion in progress; success = conversion succeeded; failed = conversion failed; timeout = conversion timed out
pendingprocessingsuccessfailedtimeout
ConvertedFileIdOptionalstring
FileId of the converted PDF; only non-empty when TaskStatus=success. Can be used directly as Documents[].FileId in QuickCreateEnvelope
TaskMessageOptionalstring
Task description text (brief note on success / failure); may be empty

Response Example

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "Tasks": [
        {
          "TaskId": "20260709175117139808",
          "TaskStatus": "success",
          "ConvertedFileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
          "TaskMessage": ""
        },
        {
          "TaskId": "20260709175117139809",
          "TaskStatus": "processing",
          "ConvertedFileId": "",
          "TaskMessage": ""
        }
      ]
    }
  }
}

Error Codes

Error CodeDescription
INVALID_REQUESTInvalid parameters (TaskIds is empty, count exceeds 50, etc.)
OPENAPI.OPERATOR_USER_NOT_FOUNDThe X-Operator-User-Id is not a member of this space
INTERNAL_ERRORInternal service error
Create File Conversion TaskQuick Create Envelope