---
title: "Start a new Flow instance"
method: POST
path: "/experimental/flow/instances/start"
tags: ["Instances"]
---

# Start a new Flow instance

`POST /experimental/flow/instances/start`

## Request

- Base URL: `https://scrive.com`
- URL: `https://scrive.com/experimental/flow/instances/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/instances/start/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates and starts a new Flow instance.

Before starting the 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.

## Request body

- StartInstance
  - `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: This object specifies concrete values for the abstract process parameters.
    - `documents` object, required
    - `users` object, required
    - `messages` object, required
  - `callback` Callback: 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.
  - `automatic_document_redirects` 'last_action' | 'always' | 'never': Automatic redirects on document actions. Defines if and when the participant will be automatically redirected to perform a document action. Participants are never redirected when they have a non-document action to perform.
  - `accessible_duration` object: How long before a successfully finished process becomes inaccessible for its participants. It cannot exceed 365 days in total.
    - `days` integer
    - `hours` integer
    - `minutes` integer
  - `language` 'sv' | 'en' | 'de' | 'fr' | 'it' | 'es' | 'pt' | 'nl' | 'da' | 'no' | 'el' | 'fi' | 'is' | 'et' | 'lv' | 'lt' | 'cs' | 'pl' | 'hu'
  - `object_version` integer: Object version of the instance. The number is incremented whenever the instance is updated.
  - `single_document_process` boolean
  - `upcoming_documents` 'hidden' | 'visible': Configures how participants see documents that they cannot act on yet. With the `hidden` option, a participant sees a document only when they can sign, approve or view it. With the `visible` option, a participant also sees the documents of their future steps. These documents are shown as not yet available and the participant cannot open them.

## 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`

---

[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)