Instances

Start a new Flow instance

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.

post/experimental/flow/instances/start

Request

Base URL
https://scrive.com
Auth
- HTTP oauth1
- or OAuth 2
  Authorization code/oauth2/auth
  Token URL/oauth2/token
  Scopesfull
- or 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.

Request body

titlestring

folder_idstring

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.

language'sv' | 'en' | 'de' | 'fr' | 'it' | 'es' | 'pt' | 'nl' | 'da' | 'no' | 'el' | 'fi' | 'is' | 'et' | 'lv' | 'lt' | 'cs' | 'pl' | 'hu'

object_versioninteger

Object version of the instance. The number is incremented whenever the instance is updated.

single_document_processboolean

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.

Example request

{
  "process": {
    "allow-rejections": true,
    "automatic-reminders": [],
    "dsl-version": "0.2.0",
    "stages": [
      {
        "initial-stage": {
          "actions": [
            {
              "notify": {
                "kind": "standard",
                "methods": {
                  "email": "msg1",
                  "email-link-only": null,
                  "sms": "msg2"
                },
                "users": [
                  "user1"
                ]
              }
            }
          ],
          "expect": {
            "signed-by": {
              "documents": [
                "doc1",
                "doc2"
              ],
              "users": [
                "user1"
              ]
            }
          }
        }
      }
    ]
  },
  "process_parameters": {
    "documents": {
      "doc1": "123"
    },
    "messages": {
      "msg1": "foobar"
    },
    "users": {
      "user1": {
        "auth_to_view": {
          "attempts_per_sms": 1,
          "max_failures": 3,
          "provider": "sms_otp"
        },
        "auth_to_view_archived": null,
        "id": "foo@example.com",
        "id_type": "email"
      }
    }
  },
  "callback": {
    "auth": {
      "password": "password",
      "type": "basic",
      "user": "user"
    },
    "url": "https://www.example.com/",
    "version": 1
  },
  "duration": {
    "days": 15,
    "hours": 7,
    "minutes": 42
  },
  "folder_id": "456",
  "accessible_duration": {
    "days": 15,
    "hours": 7,
    "minutes": 42
  },
  "language": "en",
  "object_version": 5
}

Response

idstring uuid required

Unique identifier of the instance.

titlestring

access_linksobject required

The execution status of the Flow instance.

startedstring yyyy-mm-ddThh:MM:ssZ required

finishedstring yyyy-mm-ddThh:MM:ssZ

last_eventstring yyyy-mm-ddThh:MM:ssZ required

trashedstring yyyy-mm-ddThh:MM:ssZ

author_idstring required

Unique Scrive User ID.

folder_idstring required

Unique Scrive Folder ID.

timeoutstring yyyy-mm-ddThh:MM:ssZ

The date when the instance times out.

documentsDocumentID[] 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_reminderstring 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.

Example response

{
  "access_links": {
    "user1": "https://some-env.scrive.com/experimental/flow/overview/eb4af357-28c9-410f-b432-66860955bc13/user1/ba5d504d14618def"
  },
  "admin_actions": [
    {
      "action": "notify_participant",
      "participant_id": "78b4265b-e96e-4172-97b8-1144f6e71729"
    }
  ],
  "author_id": "123",
  "callback": {
    "auth_type": "none",
    "url": "https://www.example.com/",
    "version": 1
  },
  "documents": [
    "123"
  ],
  "finished": null,
  "folder_id": "456",
  "id": "30602e94-4205-4fa0-86b7-49205503c22b",
  "initiator": "flow_api",
  "last_event": "2021-05-04T00:00:00Z",
  "latest_reminder": "2026-01-15T09:30:00Z",
  "participants": [
    {
      "authentications": [
        {
          "label": "authId",
          "max_attempts_reached": false,
          "parameters": {
            "attempts_per_sms": 5,
            "mobile_number": null,
            "provider": "sms_otp"
          },
          "type": "standard"
        }
      ],
      "automatic_reminder": {
        "date": "2026-01-15T09:30:00Z",
        "settings": {
          "date": {
            "days_delay": 7,
            "repeat": null,
            "time": null,
            "type": "relative"
          },
          "method": "email"
        }
      },
      "dsl_name": "user1",
      "latest_reminder": "2021-05-04T00:00:00Z",
      "participant_id": "78b4265b-e96e-4172-97b8-1144f6e71729",
      "tags": [
        {
          "category": "full_name",
          "value": "John Doe"
        },
        {
          "category": "email",
          "value": "private.user@example.com"
        },
        {
          "category": "email",
          "value": "corporate.user@example.com"
        }
      ]
    }
  ],
  "process": {
    "allow-rejections": true,
    "automatic-reminders": [],
    "dsl-version": "0.2.0",
    "stages": [
      {
        "initial-stage": {
          "actions": [
            {
              "notify": {
                "kind": "standard",
                "methods": {
                  "email": "msg1",
                  "email-link-only": null,
                  "sms": "msg2"
                },
                "users": [
                  "user1"
                ]
              }
            }
          ],
          "expect": {
            "signed-by": {
              "documents": [
                "doc1",
                "doc2"
              ],
              "users": [
                "user1"
              ]
            }
          }
        }
      }
    ]
  },
  "process_parameters": {
    "documents": {
      "doc1": "123"
    },
    "messages": {
      "msg1": "foobar"
    },
    "users": {
      "user1": {
        "auth_to_view": {
          "attempts_per_sms": 1,
          "max_failures": 3,
          "provider": "sms_otp"
        },
        "auth_to_view_archived": null,
        "id": "foo@example.com",
        "id_type": "email"
      }
    }
  },
  "started": "2021-01-27T00:00:00Z",
  "state": {
    "available_actions": [
      {
        "document": "123",
        "type": "sign",
        "user": {
          "id": "foo@example.com",
          "id_type": "email"
        }
      }
    ]
  },
  "status": "in_progress",
  "timeout": null,
  "title": null,
  "trashed": null
}

Changes

No recorded changes to this operation across all 1 revision of this API.