---
title: "Start a case instance"
method: POST
path: "/cmmn-runtime/case-instances"
tags: ["Case Instances"]
---

# Start a case instance

`POST /cmmn-runtime/case-instances`

## Request

- Base URL: `https://developer-docs.flowable.com/cmmn-api`
- URL: `https://developer-docs.flowable.com/cmmn-api/cmmn-runtime/case-instances`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/flowable/apis/flowable-cmmn-rest-api/docs/cmmn-runtime/case-instances/post.ts> (a function with typed inputs; its response is checked against the schema)

Note that also a *transientVariables* property is accepted as part of this json, that follows the same structure as the *variables* property.

Only one of *caseDefinitionId* or *caseDefinitionKey* an be used in the request body.

Parameters *businessKey*, *variables* and *tenantId* are optional.

If tenantId is omitted, the default tenant will be used.

 It is possible to send variables, transientVariables and startFormVariables in one request.

More information about the variable format can be found in the REST variables section.

 Note that the variable-scope that is supplied is ignored, case-variables are always local.

## Request body

- CaseInstanceCreateRequest: Only one of caseDefinitionId or caseDefinitionKey can be used in the request body
  - `caseDefinitionId` string
  - `caseDefinitionKey` string
  - `name` string
  - `businessKey` string
  - `variables` RestVariable[]
    - `name` string: Name of the variable
    - `type` string: Type of the variable.
    - `value` object: Value of the variable.
    - `valueUrl` string
    - `scope` string
  - `transientVariables` RestVariable[]
    - `name` string: Name of the variable
    - `type` string: Type of the variable.
    - `value` object: Value of the variable.
    - `valueUrl` string
    - `scope` string
  - `startFormVariables` RestVariable[]
    - `name` string: Name of the variable
    - `type` string: Type of the variable.
    - `value` object: Value of the variable.
    - `valueUrl` string
    - `scope` string
  - `outcome` string
  - `tenantId` string
  - `overrideDefinitionTenantId` string
  - `returnVariables` boolean

## Response `201`

Indicates the case instance was created.

- CaseInstanceResponse
  - `id` string
  - `name` string
  - `url` string
  - `businessKey` string
  - `businessStatus` string
  - `dueDate` string, date-time
  - `claimTime` string, date-time
  - `claimedBy` string
  - `startTime` string, date-time
  - `startUserId` string
  - `state` string
  - `ended` boolean
  - `caseDefinitionId` string
  - `caseDefinitionUrl` string
  - `caseDefinitionName` string
  - `caseDefinitionDescription` string
  - `parentId` string
  - `callbackId` string
  - `callbackType` string
  - `referenceId` string
  - `referenceType` string
  - `variables` RestVariable[]
    - `name` string: Name of the variable
    - `type` string: Type of the variable.
    - `value` object: Value of the variable.
    - `valueUrl` string
    - `scope` string
  - `tenantId` string
  - `completed` boolean

## Other responses

- `400`: Indicates either the case definition was not found (based on id or key), no process is started by sending the given message or an invalid variable has been passed. Status description contains additional information about the error.

---

[API](https://skmtc.dev/flowable/apis/flowable-cmmn-rest-api.md) - [All operations](https://skmtc.dev/flowable/apis/flowable-cmmn-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/flowable/apis/flowable-cmmn-rest-api/revisions/afdfa1fcacd0?raw)