---
title: "Start a Flow instance from a draft"
method: POST
path: "/experimental/flow/drafts/{draft_id}/start"
tags: ["Drafts"]
---

# Start a Flow instance from a draft

`POST /experimental/flow/drafts/{draft_id}/start`

## Request

- Base URL: `https://scrive.com`
- URL: `https://scrive.com/experimental/flow/drafts/{draft_id}/start`
- Auth: one of:
  - HTTP oauth1
  - OAuth 2
    - Authorization code: `/oauth2/auth`
    - Token URL: `/oauth2/token` scopes: `full`
  - API key in cookie `sessionId` and API key in header `X-Scrive-XToken`
- TypeScript: <https://skmtc.dev/scrive/apis/scrive-flow-api/docs/experimental/flow/drafts/:draft_id/start/post.ts> (a function with typed inputs; its response is checked against the schema)

Turns a Flow draft into a Flow instance and starts it.

All the request fields are optional. They override the data in the draft. Setting any optionally nullable field to `null` will remove it from the draft.

Before turning the draft into an instance, its state is validated and the objects referenced in the `process` DSL and `process_parameters` are checked to be in a good state (for example, all documents are ready to be started).

Once the validation is finished, the documents are started and the initial action of the `process` DSL is executed.

## Path parameters

- `draft_id` string, uuid, required: Unique identifier of the requested draft.

## Request body

- StartDraft: Start a Flow draft. All the request fields are optional. Setting any optionally nullable field to null removes its previous value. Setting the folder_id field will move the draft in that folder.
  - `title` string: _This is an optionally nullable field. Setting the field to `null` will remove any previously set value of this field._
  - `process` FlowDSL: Description of the signing process in Flow DSL. Most of the strings encountered in this object are interpreted as abstract variables, to be set when a Flow instance is created. Thus one can reuse this template for multiple concrete processes with their own sets of concrete users, documents, and messages. A Flow Process is composed of stages. Every _regular_ stage consists of actions taken immediately and conditions that need to be satisfied to move to the next stage. The last stage in the `stages` list may be defined as a _confirmation_ stage. A confirmation stage is a special case that consists of a notification action with its `kind` field set to "confirmation" and an empty set of `expect` conditions. If missing, the old per-document notifications will be sent out. This behaviour will change, from sending per-document confirmation notifications by default, to sending unified flow confirmation notifications, in the future.
    - `stages` FlowDSLStage[], required
      - union
        - FlowDSLStageRegular: Stage of a Flow process. It consists of actions taken immediately and conditions that need to be satisfied to move to the next stage.
        - FlowDSLStageConfirmation: A Confirmation stage is a special case that consists of a notification action with its `kind` field set to "confirmation" and empty set of `expect` conditions. This stage must be at the end of `stages` list. If missing, the old per-document notifications will be sent out. This behaviour will change, from sending per-document confirmation notifications by default, to sending unified flow confirmation notifications, in the future.
    - `dsl-version` string, required: Process version
    - `allow-rejections` boolean: Allow participants to reject the instance
    - `automatic-reminders` AutomaticReminder[]
      - `user-name` string, required: The placeholder name for a participant in a process.
      - `date` union, required: Specifies when the reminder should be sent.
        - object
          - `type` 'absolute', required: The reminder time is a specific UTC date and time.
          - `date_time` string, yyyy-mm-ddThh:MM:ssZ, required: The UTC date and time for the reminder.
        - object
          - `type` 'relative', required: The reminder is sent after a specific number of days of inactivity.
          - `days_delay` integer, required: Number of days before a reminder is sent.
          - `time` ReminderRelativeTime: Time of day in a specific time zone.
            - `time_of_day` string, hh:MM:ss, required: Time of day when the reminder will be sent.
            - `time_zone` string, required: The [IANA time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) TZ identifier. For example: `Europe/Stockholm`, or `Etc/UTC`
          - `repeat` 'never' | 'periodically': Whether the reminder repeats. With `periodically`, a new reminder is scheduled every time one is sent, using the same `days_delay` and `time`, for as long as the participant still has pending actions and the instance is running. Omitting the field is equivalent to `never`, in which case a single reminder is sent.
      - `method` 'email' | 'sms' | 'email-and-sms', required: Notification method
  - `process_parameters` ProcessParameters: This object specifies concrete values for the abstract process parameters.
    - `documents` object, required
    - `users` object, required
    - `messages` object, required
  - `callback` OptionalNullableFieldCallback: Callback object containing callback URL and optional authentication data.
    - `url` string, required: An absolute https or http URL for callback purposes.
    - `auth` union: Authentication method for the callback.
      - object: Basic callback authentication
        - `type` 'basic', required
        - `user` string, required
        - `password` string, required
      - object
        - `type` 'none', required
    - `version` 'v1', required: The Flow callback version that you would like to use.
  - `duration` object: How long before an in-progress instance times out. It cannot exceed 365 days in total.
    - `days` integer
    - `hours` integer
    - `minutes` integer
  - `folder_id` string: Unique Scrive Folder ID.

## Response `201`

- GetInstance
  - `id` string, uuid, required: Unique identifier of the instance.
  - `title` string
  - `process` FlowDSL, required: Description of the signing process in Flow DSL. Most of the strings encountered in this object are interpreted as abstract variables, to be set when a Flow instance is created. Thus one can reuse this template for multiple concrete processes with their own sets of concrete users, documents, and messages. A Flow Process is composed of stages. Every _regular_ stage consists of actions taken immediately and conditions that need to be satisfied to move to the next stage. The last stage in the `stages` list may be defined as a _confirmation_ stage. A confirmation stage is a special case that consists of a notification action with its `kind` field set to "confirmation" and an empty set of `expect` conditions. If missing, the old per-document notifications will be sent out. This behaviour will change, from sending per-document confirmation notifications by default, to sending unified flow confirmation notifications, in the future.
    - `stages` FlowDSLStage[], required
      - union
        - FlowDSLStageRegular: Stage of a Flow process. It consists of actions taken immediately and conditions that need to be satisfied to move to the next stage.
        - FlowDSLStageConfirmation: A Confirmation stage is a special case that consists of a notification action with its `kind` field set to "confirmation" and empty set of `expect` conditions. This stage must be at the end of `stages` list. If missing, the old per-document notifications will be sent out. This behaviour will change, from sending per-document confirmation notifications by default, to sending unified flow confirmation notifications, in the future.
    - `dsl-version` string, required: Process version
    - `allow-rejections` boolean: Allow participants to reject the instance
    - `automatic-reminders` AutomaticReminder[]
      - `user-name` string, required: The placeholder name for a participant in a process.
      - `date` union, required: Specifies when the reminder should be sent.
        - object
          - `type` 'absolute', required: The reminder time is a specific UTC date and time.
          - `date_time` string, yyyy-mm-ddThh:MM:ssZ, required: The UTC date and time for the reminder.
        - object
          - `type` 'relative', required: The reminder is sent after a specific number of days of inactivity.
          - `days_delay` integer, required: Number of days before a reminder is sent.
          - `time` ReminderRelativeTime: Time of day in a specific time zone.
            - `time_of_day` string, hh:MM:ss, required: Time of day when the reminder will be sent.
            - `time_zone` string, required: The [IANA time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) TZ identifier. For example: `Europe/Stockholm`, or `Etc/UTC`
          - `repeat` 'never' | 'periodically': Whether the reminder repeats. With `periodically`, a new reminder is scheduled every time one is sent, using the same `days_delay` and `time`, for as long as the participant still has pending actions and the instance is running. Omitting the field is equivalent to `never`, in which case a single reminder is sent.
      - `method` 'email' | 'sms' | 'email-and-sms', required: Notification method
  - `process_parameters` ProcessParameters, required: This object specifies concrete values for the abstract process parameters.
    - `documents` object, required
    - `users` object, required
    - `messages` object, required
  - `state` InstanceState, required: This object displays the list of actions available to the participant.
    - `available_actions` InstanceUserActionForAuthor[], required
      - `type` 'approve' | 'sign' | 'view' | 'reject' | 'redirect', required: An event performed by a participant upon a document.
      - `user` union, required: A Flow user ID is an ID together with a type specifying what kind of an ID it is. The reason for this is that Document signatories can be identified in several ways and we need to support them all. Types `email`, `phone_number` and `full_name` can be specified if a signatory is determined in one of these ways. `full_name` expects first name and second name to be connected together with space exactly in this order. If a signatory is a Scrive user (this is the case for authors) we can specify that using the `user_id` type.
        - object
          - `id_type` 'email', required
          - `id` string, required
        - object
          - `id_type` 'phone_number', required
          - `id` string, required
        - object
          - `id_type` 'user_id', required
          - `id` string, required: Unique Scrive User ID.
        - object
          - `id_type` 'full_name', required
          - `id` string, required
      - `document` string: Unique identifier for a document.
  - `access_links` object, required
  - `admin_actions` AdminApiAction[], required
    - union: Action which can be performed by the instance author.
      - object
        - `action` 'notify_participant', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
      - object
        - `action` 'cancel_instance', required
      - object
        - `action` 'prolong_instance', required
        - `max_days` integer, required: Prolongation duration in days.
      - object
        - `action` 'reset_auth_attempts', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
        - `auth_label` string: Authentication ID to enable complex authentication schemas.
      - object
        - `action` 'reset_authentication_attempts', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
        - `authentication` 'view' | 'view_archived' | 'sign', required
      - object
        - `action` 'admin_form', required
        - `form_id` AdminFormId, required: Admin Form ID
          - `id` 'participant_form', required
          - `participant_id` string, uuid, required: Unique identifier of the participant.
        - `schema` Schema, required: JSON Schema
        - `ui_schema` UiSchema: UI Schema
        - `default_value` unknown
      - object
        - `action` 'complete_redirect', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
        - `url` string, url, required: A URL string
      - object
        - `action` 'modify_reminder_settings', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
      - object
        - `action` 'delete_reminder_settings', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
      - object
        - `action` 'cancel_reminder', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
      - object
        - `action` 'modify_participant_info', required
        - `participant_id` string, uuid, required: Unique identifier of the participant.
        - `invitations_sent` InvitationKind[], required
        - `authentication_modifiable` boolean, required
  - `participants` GetParticipant[], required
    - `participant_id` string, uuid, required: Unique identifier of the participant.
    - `dsl_name` string, required: The placeholder name for a participant in a process.
    - `tags` GetParticipantTag[], required
      - `category` string, required
      - `value` string, required
    - `authentications` ParticipantAuthentication[], required
      - union
        - object
          - `type` 'standard', required
          - `label` string: Authentication ID to enable complex authentication schemas. This field is deprecated and will be removed in the future.
          - `max_attempts_reached` boolean, required
          - `parameters` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `type` 'sign', required
          - `label` string: Authentication ID to enable complex authentication schemas. This field is deprecated and will be removed in the future.
          - `max_attempts_reached` boolean, required
          - `parameters` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
    - `automatic_reminder` AutomaticReminderDetail, required: Automatic reminder details for the participant.
      - `date` string, yyyy-mm-ddThh:MM:ssZ: The scheduled date for the participant's automatic reminder.
      - `settings` ParticipantReminderSettings: Automatic reminder settings for a participant.
        - `date` union, required: Specifies when the reminder should be sent.
          - object
            - `type` 'absolute', required: The reminder time is a specific UTC date and time.
            - `date_time` string, yyyy-mm-ddThh:MM:ssZ, required: The UTC date and time for the reminder.
          - object
            - `type` 'relative', required: The reminder is sent after a specific number of days of inactivity.
            - `days_delay` integer, required: Number of days before a reminder is sent.
            - `time` ReminderRelativeTime: Time of day in a specific time zone.
              - …
            - `repeat` 'never' | 'periodically': Whether the reminder repeats. With `periodically`, a new reminder is scheduled every time one is sent, using the same `days_delay` and `time`, for as long as the participant still has pending actions and the instance is running. Omitting the field is equivalent to `never`, in which case a single reminder is sent.
        - `method` 'email' | 'sms' | 'email_and_sms', required: Automatic reminder delivery method.
    - `latest_reminder` string, yyyy-mm-ddThh:MM:ssZ: Timestamp of the most recent reminder sent to this participant, covering both manual, bulk and automatic reminders.
  - `status` 'in_progress' | 'finalising' | 'canceled' | 'rejected' | 'completed' | 'failed' | 'timed_out', required: The execution status of the Flow instance.
  - `started` string, yyyy-mm-ddThh:MM:ssZ, required
  - `finished` string, yyyy-mm-ddThh:MM:ssZ
  - `last_event` string, yyyy-mm-ddThh:MM:ssZ, required
  - `trashed` string, yyyy-mm-ddThh:MM:ssZ
  - `callback` GetCallback: Callback object containing callback URL and the authentication type.
    - `url` string, required: An absolute https or http URL for callback purposes.
    - `auth_type` 'none' | 'basic', required
    - `version` 'v1', required: The Flow callback version that you would like to use.
  - `author_id` string, required: Unique Scrive User ID.
  - `folder_id` string, required: Unique Scrive Folder ID.
  - `timeout` string, yyyy-mm-ddThh:MM:ssZ: The date when the instance times out.
  - `documents` DocumentID[], required
  - `initiator` 'flow_api' | 'id_check' | 'journey_service', required: Who initiated the Flow instance. **Note**: This value is for internal use only and subject to change without prior notice.
  - `latest_reminder` string, yyyy-mm-ddThh:MM:ssZ: Timestamp of the most recent reminder sent in this instance, across all participants and covering both manual, bulk and automatic reminders.

## Other responses

- `400`: Invalid `body`
- `404`: `draft_id` not found

---

[API](https://skmtc.dev/scrive/apis/scrive-flow-api.md) - [All operations](https://skmtc.dev/scrive/apis/scrive-flow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scrive/apis/scrive-flow-api/revisions/f9b2836863f2?raw)