Create a Workflow to enable structured processing of data in a Subject Record.

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

Usage Info

The Workflow represents a structured process or series of activities performed using the Subject Record data. This method initiates the workflow process, optionally creating a new Subject Record if one isn't provided. By default, workflows automatically enter the STARTED state unless the state parameter is provided.

Use this method to begin application processes, compliance reviews, or other structured data collection activities.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
account_id	string	Yes	The account where the Workflow will be created. The Account ID is supplied to you when you receive your credentials.
workflow	object	Yes	The workflow parameter defined in the tables below.

Workflow Parameters

Parameter	Type	Required	Description
type	string	Yes	The type of Workflow. Must be one of WORKFLOW_TYPES.
state	string	No	The initial state for the Workflow. Must be `CREATED` or `STARTED` WORKFLOW_STATES. If not provided, the default state is `STARTED`.
subject_record_id	string	No	The Subject Record to associate with the Workflow. If the value is not supplied then a new Subject Record of the appropriate type is created.
details	object	Depends	Required if type is `BUSINESS_APPLICATION`, otherwise should not be included. One of the Workflow details objects. The table below maps the Workflow Type to the Workflow Details.

Workflow Type to Details Mapping

Workflow Type	Workflow Details
BUSINESS_APPLICATION	Business Application Details

Business Application Details Parameters

Parameter	Type	Required	Description
applying_user	object	Yes	The object containing information about the applying user. This information is used for identification, communication, and authentication.
pricing_model_id	string	No	The ID of the pricing model to use. Different pricing models allow a single account to allow different rules for determining pricing. Pricing models are created during account setup and are optional.
equipment_collection_id	string	No	The ID of the equipment collection catalog to use. Equipment collections are created during account setup and is optional.
referrer_value	string	No	The customer provided value to identify how application was referred, such as a marketplace, website, or sales person. This field is limited to 100 characters.

Applying User Parameters

Parameter	Type	Required	Description
email	string	Yes	The email address of the applying user. The email must be a validly formatted email address. NOTE: Depending upon the account configuration, this email address may need to be unique for all Business-Application-type Workflows for the given `account_id`.
first_name	string	No	The first name of the applying user.
last_name	string	No	The last name of the applying user.

Examples

Creating a Business Application Workflow

{
  "account_id": "sb_j8gh53b",
  "workflow": {
    "type": "BUSINESS_APPLICATION",
    "subject_record_id": "sr_163Gh1ONk6BCHF9iYVDHcv",
    "details": {
      "business_application_details": {
        "applying_user": {
          "email": "[email protected]"
        },
        "referrer_value": "UAYACG123"
      }
    }
  }
}

Creating an Account Provisioning Workflow

{
  "account_id": "sb_j8gh53b",
  "workflow": {
    "type": "ACCOUNT_PROVISIONING"
  }
}

Response

Data

Parameter	Type	Description
workflow	object	The workflow parameter defined in the table below.

Workflow Parameters

Parameter	Type	Description
workflow_id	string	The identifier for the Workflow just created.
subject_record_id	string	The identifier for the Subject Record just created or provided. This value is always returned.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_6OI5blm21ZoSlq0PC3RqJV",
    "version": "2025-03-24"
  },
  "data": {
    "workflow": {
      "workflow_id": "w_2dJFFW3HY8a3zOjqwUXhQc",
      "subject_record_id": "sr_4vrv6U1vdpc341MO7cF8pE"
    }
  }
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	The `type` provided is not one of the WORKFLOW_TYPES. Required parameters not provided. Invalid values provided.
ENTITY_NOT_FOUND	400	The `account_id`, `subject_record_id`, `pricing_model_id`, or `equipment_selection_id` provided does not exist.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.
ACCOUNT_CONFIGURATION_VIOLATION	400	Account configuration 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	CROSS_ACCOUNT_REFERENCE	The Subject Record must belong to the same account as specified in the account_id parameter.
Workflow	INVALID_SUBJECT_RECORD_TYPE	The Subject Record type is incompatible with the Workflow type. For example, a Business Application workflow requires a Business-type Subject Record.
Workflow	INVALID_WORKFLOW_TYPE	The method is not supported for the current Workflow type.
Workflow	SUBJECT_RECORD_WORKFLOW_TYPE_LIMIT	The Subject Record cannot be associated with multiple workflows of the same type. Currently, the types with a limit of one workflow per Subject Record include: `Business Application`

Account Configuration Violations

When a ACCOUNT_CONFIGURATION_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	DUPLICATE_EMAIL	The email address provided for the applying user is already in use by another Business-Application-type Workflow for the same account. This error code is only returned when the account does not support multiple applications per email.