Add multiple Required Document entities to a Workflow in a single batch operation.

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

Usage Info

This method allows you to add multiple required documents to a workflow in a single batch operation, specifying document types and their requirement descriptions. Each required document in the request is processed individually, with the response containing detailed results for each item including success or failure status and the created required_document_id.

The method handles duplicate detection, preventing the same document_type_code from being added multiple times in a single request, and returns the existing required_document_id if a document type already exists in the workflow.

Use this method when manually adding required documents beyond those auto-calculated by the system, requesting additional supporting documents during underwriting review, creating custom document requirements specific to individual workflows, or bulk-adding multiple document requirements in a single operation for efficiency. The created required_documents can then be fulfilled by linking uploaded 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.
required_documents	array	Yes	An array of Required Document objects to add. See required document parameters below.
notification_parameters	object	No	Optional notification settings. See notification parameters below.

Required Document Parameters

Parameter	Type	Required	Description
document_type_code	string	Yes	The document type code. Must be one of the DOCUMENT_TYPE_CODES. Use "ADDITIONAL" for custom ad-hoc requirements. When "ADDITIONAL" is used, account document type validation is bypassed.
requirement_text	string	Yes	The specific requirement or instruction text for this document.

Notification Parameters

Parameter	Type	Required	Description
notify	boolean	No	Whether to send notification. Defaults to `false`.
message	string	No	Custom notification message to include.

Examples

Example 1: Adding Multiple Required Documents

{
  "workflow_id": "w_LKQpQvG7r6BWXBzrvFvI5",
  "required_documents": [
    {
      "document_type_code": "PASSPORT",
      "requirement_text": "Valid passport required"
    },
    {
      "document_type_code": "BANK_STATEMENTS",
      "requirement_text": "3 months of bank statements"
    }
  ]
}

Example 2: With Notification Parameters

{
  "workflow_id": "w_LKQpQvG7r6BWXBzrvFvI5",
  "notification_parameters": {
    "notify": true,
    "message": "Additional documents have been requested for your application"
  },
  "required_documents": [
    {
      "document_type_code": "TAX_RETURNS",
      "requirement_text": "Last 2 years of business tax returns"
    }
  ]
}

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 Required Documents Processed Successfully

{
  "meta": {
    "status": "BATCH_PROCESSED",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24",
    "total_requests": 2,
    "success_count": 2,
    "failure_count": 0
  },
  "results": [
    {
      "status": "SUCCESS",
      "request": {
        "document_type_code": "PASSPORT",
        "requirement_text": "Valid passport required"
      },
      "data": {
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
      }
    },
    {
      "status": "SUCCESS",
      "request": {
        "document_type_code": "BANK_STATEMENTS",
        "requirement_text": "3 months of bank statements"
      },
      "data": {
        "required_document_id": "rd_2bJyTnZKcvL3j9h7TYXtSF"
      }
    }
  ]
}

Example 2: Mixed Results with Errors

{
  "meta": {
    "status": "BATCH_PROCESSED",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24",
    "total_requests": 2,
    "success_count": 1,
    "failure_count": 1
  },
  "results": [
    {
      "status": "SUCCESS",
      "request": {
        "document_type_code": "PASSPORT",
        "requirement_text": "Valid passport required"
      },
      "data": {
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
      }
    },
    {
      "status": "ERROR",
      "request": {
        "document_type_code": "INVALID_CODE",
        "requirement_text": "Some requirement"
      },
      "errors": [
        {
          "code": "BAD_REQUEST",
          "message": "Invalid document type code provided."
        }
      ]
    }
  ]
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Invalid values provided.
ENTITY_NOT_FOUND	400	The `workflow_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.
RequiredDocument	DOCUMENT_TYPE_NOT_ASSIGNABLE	Document_type_code is not assignable in this account.