Request document files for multiple Required Documents in a single batch operation.

POST http://api.kompliant.com/workflow.requiredDocument.batchRequestDocument (OpenAPI specification)

Usage Info

This method allows you to initiate file requests for multiple required documents in a single batch operation. Each required document in the request is processed individually, with the response containing detailed results for each item including success or failure status. The method validates that required documents exist, are active, and belong to the specified workflow.

Use this method when prompting applicants to upload files for specific required documents, when sending batch notifications to request multiple documents at once, when triggering email or in-app notifications for document collection, or when managing document request workflows that need to track when files were requested. This is particularly useful during the document collection phase of underwriting to efficiently request all outstanding documents in a single operation.

After files are requested, applicants can upload documents using the document.create endpoint, which can then be linked to required documents using the workflow.requiredDocument.fulfillment.batchAdd endpoint.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
workflow_id	string	Yes	The identifier for the Workflow with `w_` prefix format.
required_documents	array	Yes	An array of Required Document identifiers to request files for. See parameters below.

Required Document Parameters

Parameter	Type	Required	Description
required_document_id	string	Yes	The identifier for the Required Document with `rd_` prefix format.

Examples

Example 1: Requesting Files for Multiple Required Documents

{
  "workflow_id": "w_LKQpQvG7r6BWXBzrvFvI5",
  "required_documents": [
    {
      "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
    },
    {
      "required_document_id": "rd_2bJyTnZKcvL3j9h7TYXtSF"
    },
    {
      "required_document_id": "rd_3cKzUnALdwM4k8i6UZYuTG"
    }
  ]
}

Response

Data

The response uses the batch processing format with individual results for each required document from the request.

Parameter	Type	Description
meta	object	Batch processing metadata. Parameters are documented on the batch meta responses reference .
results	array	An array of individual result objects for each required document in the request. See result parameters below.

Result Parameters

Parameter	Type	Description
status	string	Status of this individual operation. Either `SUCCESS` or `ERROR`.
request	object	Echo of the original request data for this item.
data	object	Empty object for successful operations.
errors	array	Error details for failed operations. Each error contains `code`, `message`, and optionally `details`, `sub_code`, and `entity_type`.

Examples

Example 1: All File Requests Processed Successfully

{
  "meta": {
    "status": "BATCH_PROCESSED",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24",
    "total_requests": 3,
    "success_count": 3,
    "failure_count": 0
  },
  "results": [
    {
      "status": "SUCCESS",
      "request": {
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
      },
      "data": {}
    },
    {
      "status": "SUCCESS",
      "request": {
        "required_document_id": "rd_2bJyTnZKcvL3j9h7TYXtSF"
      },
      "data": {}
    },
    {
      "status": "SUCCESS",
      "request": {
        "required_document_id": "rd_3cKzUnALdwM4k8i6UZYuTG"
      },
      "data": {}
    }
  ]
}

Example 2: Mixed Results with Errors

{
  "meta": {
    "status": "BATCH_PROCESSED",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24",
    "total_requests": 3,
    "success_count": 1,
    "failure_count": 2
  },
  "results": [
    {
      "status": "SUCCESS",
      "request": {
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
      },
      "data": {}
    },
    {
      "status": "ERROR",
      "request": {
        "required_document_id": "rd_nonexistent"
      },
      "errors": [
        {
          "code": "ENTITY_NOT_FOUND",
          "message": "The given entity(s) does not exist.",
          "details": [
            {
              "required_document_id": "rd_nonexistent"
            }
          ]
        }
      ]
    },
    {
      "status": "ERROR",
      "request": {
        "required_document_id": "rd_inactive"
      },
      "errors": [
        {
          "code": "BAD_REQUEST",
          "message": "Cannot request files for an inactive required document."
        }
      ]
    }
  ]
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Invalid values provided. Cannot request files for an inactive required document.
ENTITY_NOT_FOUND	404	The `workflow_id` or `required_document_id` provided does not exist.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Workflow	WORKFLOW_ENDED	The Workflow is in an ENDED state and cannot completed.