Add multiple Fulfillment entities linking Documents to Required Documents in a single batch operation.

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

Usage Info

This method allows you to link multiple uploaded Documents to their corresponding required documents in a single batch operation, establishing fulfillment relationships with optional decision statuses. Each fulfillment in the request is processed individually, with the response containing detailed results for each item including success or failure status. The method validates that documents exist, belong to the same subject record as the workflow, and prevents duplicate fulfillments.

Use this method when documents have been uploaded and need to be associated with Required Documents, when processing multiple document submissions simultaneously to improve efficiency, when setting initial review statuses for uploaded Documents, or when automating Document Fulfillment workflows that link multiple Documents at once.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
workflow_id	string	Yes	The identifier for the Workflow with `w_` prefix format.
fulfillments	array	Yes	An array of Fulfillment objects to add. See fulfillment parameters below.

Fulfillment Parameters

Parameter	Type	Required	Description
document_id	string	Yes	The identifier for the Document.
required_document_id	string	Yes	The identifier for the Required Document.
decision_status	string	No	The decision status for this fulfillment. Must be one of the FULFILLMENT_DECISION_STATUSES. If not provided, defaults to `NEEDS_REVIEW`.

Example

Example 1: Adding Multiple Fulfillments with Decision Status

{
  "workflow_id": "w_LKQpQvG7r6BWXBzrvFvI5",
  "fulfillments": [
    {
      "document_id": "d_1rQYvnUQdcatd4TcZQu0l8",
      "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8",
      "decision_status": "NEEDS_REVIEW"
    },
    {
      "document_id": "d_2bJyTnZKcvL3j9h7TYXtSF",
      "required_document_id": "rd_2bJyTnZKcvL3j9h7TYXtSF",
      "decision_status": "ACCEPTED"
    }
  ]
}

Example 2: Adding Fulfillments with Default Status

{
  "workflow_id": "w_LKQpQvG7r6BWXBzrvFvI5",
  "fulfillments": [
    {
      "document_id": "d_1rQYvnUQdcatd4TcZQu0l8",
      "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8"
    }
  ]
}

Response

Data

The response uses a batch processing format with individual results for each fulfillment in 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 fulfillment 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 Fulfillments 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_id": "d_1rQYvnUQdcatd4TcZQu0l8",
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8",
        "decision_status": "NEEDS_REVIEW"
      },
      "data": {}
    },
    {
      "status": "SUCCESS",
      "request": {
        "document_id": "d_2bJyTnZKcvL3j9h7TYXtSF",
        "required_document_id": "rd_2bJyTnZKcvL3j9h7TYXtSF",
        "decision_status": "ACCEPTED"
      },
      "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": {
        "document_id": "d_1rQYvnUQdcatd4TcZQu0l8",
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8",
        "decision_status": "NEEDS_REVIEW"
      },
      "data": {}
    },
    {
      "status": "ERROR",
      "request": {
        "document_id": "d_nonexistent",
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8",
        "decision_status": "NEEDS_REVIEW"
      },
      "errors": [
        {
          "code": "ENTITY_NOT_FOUND",
          "message": "The given entity(s) does not exist.",
          "details": [
            {
              "document_id": "d_nonexistent"
            }
          ]
        }
      ]
    },
    {
      "status": "ERROR",
      "request": {
        "document_id": "d_duplicate",
        "required_document_id": "rd_1rQYvnUQdcatd4TcZQu0l8",
        "decision_status": "NEEDS_REVIEW"
      },
      "errors": [
        {
          "code": "BAD_REQUEST",
          "message": "Fulfillment already exists for these entities."
        }
      ]
    }
  ]
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Invalid values provided. Fulfillment already exists for these entities.
ENTITY_NOT_FOUND	404	Document or Required Document 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.